ts-package

Prepare TypeScript library for npm publication:

1. Validate Library Setup

   Check if this is a publishable library:

   • Is there a package.json?
   • Is this intended for npm publication?
   • What type of library: React, Vue, utility, Node?
   • Target environments: Browser, Node, both?

2. Configure package.json

   Essential Fields:

   {
     "name": "@scope/package-name",
     "version": "1.0.0",
     "description": "Library description",
     "author": "Name <email>",
     "license": "MIT",
     "repository": {
       "type": "git",
       "url": "https://github.com/user/repo.git"
     },
     "keywords": ["typescript", "library"],
   
     "type": "module",
     "main": "./dist/index.cjs",
     "module": "./dist/index.js",
     "types": "./dist/index.d.ts",
   
     "exports": {
       ".": {
         "types": "./dist/index.d.ts",
         "import": "./dist/index.js",
         "require": "./dist/index.cjs"
       }
     },
   
     "files": [
       "dist",
       "README.md",
       "LICENSE"
     ],
   
     "sideEffects": false,
   
     "engines": {
       "node": ">=18"
     }
   }
   

   Verify and fix any missing or incorrect fields.

3. Set Up Build Configuration

   Recommended: tsup (Simple & Fast)

   // tsup.config.ts
   import { defineConfig } from 'tsup';
   
   export default defineConfig({
     entry: ['src/index.ts'],
     format: ['esm', 'cjs'],
     dts: true,
     splitting: false,
     sourcemap: true,
     clean: true,
     treeshake: true,
     external: [], // Add peer dependencies
   });
   

   Or configure tsc for dual package:

   // tsconfig.build.json
   {
     "extends": "./tsconfig.json",
     "compilerOptions": {
       "declaration": true,
       "declarationMap": true,
       "sourceMap": true,
       "removeComments": false
     },
     "exclude": ["**/*.test.ts", "**/*.spec.ts"]
   }
   

4. Generate Type Declarations

   Ensure high-quality .d.ts files:

   • Enable declaration: true
   • Enable declarationMap: true for IDE navigation
   • Keep JSDoc comments (removeComments: false)
   • Export all public types explicitly
   • Bundle declarations if multiple files

5. Configure Dual Package (ESM + CJS)

   Support both module systems:

   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
     "./utils": {
       "types": "./dist/utils.d.ts",
       "import": "./dist/utils.js",
       "require": "./dist/utils.cjs"
     }
   }
   

6. Verify Public API

   Check src/index.ts exports:

   • All public APIs exported
   • Types exported separately
   • No internal implementation leaked
   • Clear module boundaries

   // Good exports
   export type { User, CreateUserInput } from './types';
   export { createUser, updateUser } from './api';
   export { default as UserService } from './UserService';
   

7. Add JSDoc Documentation

   Document public APIs:

   /**
    * Creates a new user with the provided details.
    *
    * @param input - The user details
    * @returns A promise resolving to the created user
    * @throws {ValidationError} If input is invalid
    *
    * @example
    * ```typescript
    * const user = await createUser({
    *   name: 'Alice',
    *   email: '[email protected]'
    * });
    * ```
    */
   export async function createUser(
     input: CreateUserInput
   ): Promise<User>;
   

8. Configure Files to Publish

   package.json files field:

   {
     "files": [
       "dist",
       "README.md",
       "LICENSE",
       "CHANGELOG.md"
     ]
   }
   

   Or create .npmignore:

   src/
   tests/
   *.test.ts
   *.spec.ts
   tsconfig.json
   .eslintrc
   

9. Set Up Pre-Publish Scripts

   {
     "scripts": {
       "build": "tsup",
       "type-check": "tsc --noEmit",
       "test": "vitest run",
       "prepublishOnly": "npm run build && npm test"
     }
   }