Building and Publishing TypeScript Libraries to npm

Table of Contents

• Why Publish a TypeScript Library?
• Key Considerations Before Publishing
• Setting Up Your Library Project
• Configuring tsconfig.json for Libraries
• Writing TypeScript Code
• Bundling Your Library
• Preparing package.json
• Managing .npmignore or files field
• Building the Library
• Publishing to npm
• Versioning and Publishing Best Practices
• Conclusion

---

Why Publish a TypeScript Library?

Publishing your own TypeScript library allows you to:

• Share reusable code (e.g., UI components, utilities, SDKs).
• Establish credibility as an open-source contributor or expert.
• Empower your team internally or support the larger developer community.

A properly published TypeScript library ensures:

• Consumers get typed support out of the box.
• Both JavaScript and TypeScript projects can easily consume it.

---

Key Considerations Before Publishing

• Type Definitions: Ensure your .d.ts files are available.
• Build Output: Ship clean, compiled JavaScript.
• Bundling: Use tools like tsup, rollup, esbuild if necessary.
• ESModules vs CommonJS: Decide the module target.
• Tree Shaking: Export ES modules for better optimization.
• License and Readme: Add a LICENSE and README.md.

---

Setting Up Your Library Project

Create a new folder for your library:

mkdir my-awesome-lib
cd my-awesome-lib
npm init -y

Install development dependencies:

npm install --save-dev typescript

Optionally, you may add bundlers like tsup, rollup, or vite later if needed.

Project structure:

my-awesome-lib/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

---

Configuring tsconfig.json for Libraries

Here’s a minimal tsconfig.json for building a library:

{
  "compilerOptions": {
    "target": "ES2019",
    "module": "ESNext",
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist",
    "rootDir": "src",
    "moduleResolution": "Node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Key options:

• declaration: generates .d.ts files.
• outDir: where to put the build output.
• strict: ensures strong typing.

---

Writing TypeScript Code

Inside src/index.ts:

export function greet(name: string): string {
  return `Hello, ${name}!`;
}

You can structure your library better if needed (e.g., create folders like utils, components, etc.).

---

Bundling Your Library (Optional but Recommended)

Instead of just using tsc, you can bundle using tsup, rollup, or esbuild.

Example with tsup:

Install tsup:

npm install --save-dev tsup

Add a build script in your package.json:

{
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts"
  }
}

This command will:

• Create ESM and CommonJS outputs.
• Generate .d.ts types automatically.

Tsup is fast and perfect for most libraries.

---

Preparing package.json

Update your package.json carefully:

{
  "name": "my-awesome-lib",
  "version": "1.0.0",
  "description": "An awesome TypeScript library",
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsc"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/my-awesome-lib.git"
  },
  "keywords": [
    "typescript",
    "library"
  ],
  "author": "Your Name",
  "license": "MIT"
}

Important Fields:

• main: CommonJS entry.
• module: ESModule entry (for modern bundlers).
• types: Points to the TypeScript declarations.
• files: Only publish necessary files (like dist/).

---

Managing .npmignore or files Field

Instead of .npmignore, it’s better to use the files field in package.json.

If you still prefer .npmignore, make sure you exclude:

• /src
• /node_modules
• /tests
• /example
• /scripts

Example .npmignore:

src/
node_modules/
tests/
example/
scripts/
tsconfig.json

---

Building the Library

Run the build:

npm run build

It will generate:

• JavaScript files (.js or .mjs)
• Type definition files (.d.ts) inside the dist/ folder.

---

Publishing to npm

1. Login to npm:

npm login

2. Publish:

npm publish --access public

If your package name is scoped (e.g., @your-org/my-lib), you must use --access public to make it public.

3. Done! Your library is live!

---

Versioning and Publishing Best Practices

• Follow Semantic Versioning (semver):
  • MAJOR.MINOR.PATCH
  • Major = breaking changes
  • Minor = new features (no breaking)
  • Patch = fixes
• Add proper CHANGELOG.md.
• Use GitHub Releases or npm Release Notes.
• Tag your Git commits (git tag v1.0.0).
• Set up CI/CD to auto-publish on pushes (e.g., GitHub Actions).

---

Conclusion

Publishing a TypeScript library to npm the right way ensures:

• Developers get a clean and typed experience.
• Your code is reliable and future-proof.
• You and your brand build credibility in the community.

Quick Summary Workflow:

Code ➔ Build ➔ Publish ➔ Repeat (with proper versioning)