[{"id":"d2bc1942-0042-42a0-aa68-b14e4087b66e","type":"markdown","content":"---\ntitle: \"📦 From Zero to Publish: Building and Releasing Your First npm Package\"\ndescription: \"A hands-on guide to building, testing, and publishing your first npm package — from project setup and TypeScript configuration to versioning, automation, and release.\"\ntags: [\n \"npm\",\n \"Node.js\",\n \"TypeScript\",\n \"JavaScript\",\n \"Open Source\",\n \"Package Publishing\",\n \"Developer Tools\",\n \"Automation\",\n \"GitHub Actions\",\n \"CI/CD\",\n \"Versioning\",\n \"Build Setup\",\n \"Developer Tutorial\",\n \"How I Built This\"\n]\n---\n\n\n\n\n## 🪄 Introduction\n\nIf you have ever written a piece of code and thought, “Hey, I could reuse this!”, then it might be time to turn it into an npm library. Creating your own package isn’t just about sharing code — it’s about learning how to write maintainable modules, manage dependencies, and publish something others can benefit from. In this post, we will explore how to build and publish an npm library the right way, with a focus on simplicity, quality, and long-term maintainability.\n\n\n> npm (Node Package Manager) is the world’s largest software registry and the default package manager for Node.js. It allows developers to share, install, and manage reusable pieces of code — called packages or libraries — with just a few commands. Whether you’re adding a utility like lodash, a framework like React, or publishing your own library, npm provides the tools to version, distribute, and maintain JavaScript packages efficiently.\n\n---\n\n\n## Why Use npm?\n\nNPM is popular because it:\n\n- Easily manage dependencies — install, update, and remove packages with simple commands.\n\n- Leverage open-source tools — access millions of prebuilt libraries to speed up development.\n\n- Share your own work — publish and version your own packages for others to use.\n\n- Ensure consistency — lock versions and automate installations across teams and environments.\n\n- Integrate seamlessly — npm works smoothly with popular build tools, frameworks, and CI/CD pipelines.\n\n\n\n\n> To learn about the npm visit their registry [here](https://www.npmjs.com)\n\n\n\nThis tutorial focuses on building and publishing an npm library that includes styled components powered by Tailwind CSS. It also covers setting up a `CI/CD` pipeline using `GitHub Actions` and `Semantic Release` to automatically manage versioning and package publishing whenever changes are pushed to the repository. The library will be compatible with both `React Client` and `React Server` Components, and you will learn how to correctly inject the `\"use client\"` directive where needed. By the end, you will have a fully automated, modern npm library setup — ready for production and easy to maintain.\n\n--- \n\n### ⚙️ Setting Up the Project\n\nCreate a new vite project, this tutorial uses typeScript. It is recommended but not necessary.\n\n```bash\nnpm create vite@latest\n```\n\nNow set up vite for library mode.\n\n> For refrence visit [here](https://vite.dev/guide/build.html).\n\ninstall the required dependecies\n\n```bash\nnpm i class-variance-authority clsx tailwind-merge\n```\n\nDev dependencies\n\n```bash\nnpm i --save-dev tailwindcss @tailwindcss/vite rollup-preserve-directives rollup-preserve-directives vite-plugin-lib-inject-css vite-tsconfig-paths vite-plugin-dts\n```\n\nNow, during development, we don’t want to constantly test our library by manually importing it into another React component or project. Instead, we can use a powerful tool called Storybook — an isolated environment for building, previewing, and testing UI components.\nTo set it up, simply run the following command in your project directory:\n\n\n\n```bash\nnpm create storybook@latest\n```\n\n\n\n> To configure path alias you can add this too the `tsconfig.app.json`\n\n```typescript\n\"paths\": {\n\t\"@/*\": [\"src/*\"]\n},\n\n```\n\n---\n\n\n### vite.config.ts\n\nIn the vite config file, we need to determine how we bundle the javaScript\n\n\n1. Imports and Setup\n\n```typescript\n/// \n// https://vite.dev/config/\n```\nThese lines define type references for Vitest (so TypeScript can provide IntelliSense and type checking) and point to the official Vite configuration docs for reference.\n\n\n```typescript\nimport { storybookTest } from \"@storybook/addon-vitest/vitest-plugin\";\nimport tailwindcss from \"@tailwindcss/vite\";\nimport react from \"@vitejs/plugin-react\";\nimport { fileURLToPath } from \"node:url\";\nimport dts from \"vite-plugin-dts\";\nimport { defineConfig } from \"vite\";\nimport tsconfigPaths from \"vite-tsconfig-paths\";\nimport path from \"node:path\";\nimport { libInjectCss } from \"vite-plugin-lib-inject-css\";\nimport preserveDirectives from \"rollup-preserve-directives\";\n\n```\n\n2. Plugin Imports\n\n> 🧠 Understanding What’s Happening\n\nThese imports bring in key tools used throughout the config:\n- @storybook/addon-vitest/vitest-plugin – integrates Storybook stories with Vitest, allowing component stories to be tested directly.\n\n- @tailwindcss/vite – enables TailwindCSS to work seamlessly with Vite’s build pipeline.\n\n- @vitejs/plugin-react – adds React-specific features like fast refresh, JSX support, and automatic runtime configuration.\n\n- vite-plugin-dts – automatically generates and bundles .d.ts (TypeScript declaration) files for your npm library.\n\n- vite-tsconfig-paths – allows Vite to respect your tsconfig.json path aliases (like @/components).\n\n- vite-plugin-lib-inject-css – ensures your library’s CSS is automatically imported into the built bundle.\n\n- rollup-preserve-directives – helps preserve \"use client\" and \"use server\" directives after bundling.\n\n\n3. ESM-Compatible `__dirname` Handling\n\n```typescript\nconst dirname =\n\ttypeof __dirname !== \"undefined\"\n\t\t? __dirname\n\t\t: path.dirname(fileURLToPath(import.meta.url));\n\n```\n\nBecause Vite’s config runs in an ES module context, the traditional __dirname isn’t available.\nThis snippet recreates it safely so file paths can still be resolved correctly.\n\n\n4. defineConfig() – Main Vite Configuration\n\n```typescript\nplugins: [\n react(),\n tsconfigPaths(),\n dts({\n insertTypesEntry: true,\n tsconfigPath: path.resolve(dirname, \"tsconfig.app.json\"),\n }),\n tailwindcss(),\n preserveDirectives(),\n {\n ...libInjectCss(),\n enforce: \"pre\",\n },\n {\n name: \"custom-swap-directive\",\n generateBundle(_, bundle) {\n // moves \"use client\" or \"use server\" to the top of the file\n },\n },\n],\n```\n\n> 🧠 Understanding What’s Happening\n\n- react() — enables React JSX transformation and React fast refresh.\ntsconfigPaths() — resolves imports based on tsconfig.json paths.\n- dts() — generates TypeScript type definitions (.d.ts) for consumers of your npm package.\n- tailwindcss() — applies Tailwind’s PostCSS pipeline to your styles.\n- preserveDirectives() — ensures \"use client\" or \"use server\" directives survive Vite’s bundling process.\n- libInjectCss() — automatically injects CSS imports into the output library build.\n- enforce: \"pre\" ensures this runs before other plugins, so CSS is inserted early.\n- custom-swap-directive — a custom plugin that ensures the \"use client\" or \"use server\" directive always appears at the top of bundled files, which is crucial for React Server Component compatibility.\n\n\n4.2 Build Section\n\n```typescript\nbuild: {\n lib: {\n entry: path.resolve(dirname, \"src/index.ts\"),\n name: \"ConiungoUI\",\n fileName: \"coniungo-ui\",\n },\n rollupOptions: {\n external: [\"react\", \"react-dom\", \"react/jsx-runtime\", \"tailwindcss\"],\n output: {\n globals: {\n react: \"React\",\n \"react-dom\": \"ReactDOM\",\n \"react/jsx-runtime\": \"jsxRuntime\",\n tailwindcss: \"tailwindcss\",\n },\n },\n },\n},\n\n```\n\n> 🧠 Understanding What’s Happening\n\n- lib - configures Vite to build your package as a reusable library instead of a web app.\n\n- entry - The main entry file `(src/index.ts)`.\n\n- name - Global variable name when used via `

From Bugs to Breakthroughs: My Tech Journey

All articles