publish-to-npm-template

• publish-to-npm-template
• Tools
  • Typescript
    • Why use Typescript over Javascript?
  • tsup
• Steps
  • Getting started
  • Writing your project - Setting up your project structure

The serves as an example project of deploying a TypeScript project to NPM registry. The code will be transpiled for both commonjs and ESM.

• How to make your own NPM package (Step-by-Step) 📦

Tools

Typescript

typescript is a typed superset of JavaScript that compiles to plain JavaScript. It is a language for application-scale JavaScript. TypeScript adds optional types to JavaScript that support tools for large-scale JavaScript applications for any browser, for any host, on any OS. TypeScript compiles to clean, simple JavaScript code which runs on any browser, in Node.js, or in any JavaScript engine that supports ECMAScript 3 (or newer).

Why use Typescript over Javascript?

Typescript is a superset of Javascript, which means that all Javascript code is valid Typescript code. Typescript adds optional types, classes, and modules to Javascript. Typescript code is transformed into Javascript code via the Typescript compiler. Typescript is a statically typed language, which means that you can catch errors and bugs at compile time rather than at runtime. Typescript is a great tool for large-scale applications that need to be maintained over time.

tsup

tsup is a zero-config TypeScript bundler with treeshaking, incremental build, and much more. It can bundle anything that's supported by Node.js natively, namely .js, .json, .mjs. And TypeScript .ts, .tsx. CSS support is experimental.

Steps

• Go to your npm account and login
• Authenticate by running npm login
  • Verify you are logged in with npm whoami
• Create a .nvmrc file and add the version of node you are using
• Create a new directory and run npm init -y to create a new package.json file with default values then pdate the package.json file with your details.
  • As you make more changes you will update the version field incrementally.
  • The main field is the entry point to your package, in this case this is going to be commonjs and since we'll be using TypeScript we'll be transpiling it down to JavaScript. For that we'll have a specific directory called dist and this is where your JavaScript files are going to go.
    • Create a dist folder.
    • To transpile for both commonjs and ESM we'll have to add a types and module field to the package.json file.
      • Nodejs is smart enough to figure out which one to use based on the project type. If somebody does not specify the type or set it to commonjs then it automatically sticks with main.
    • Another thing you need is the types entry point which is going to be for type safety, users can import types with your package.
      • Create a types field in the package.json file.
      • Create a keywords in the package.json file. These are the keywords that will be shown on npm.

{
  "name": "publish-to-npm-template",
  "version": "1.0.0",
  "description": "A template for publishing to npm",
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsup",
    "prepublishOnly": "npm run build" // this will run the build script before publishing to npm
  },
  "keywords": ["typescript", "npm", "publish"],
  "author": "Michael O'Grady",
  "devDependencies": {},
  "license": "MIT"
}

Getting started

• npm i -g typescript tsup
• npm i -D typescript tsup
• Create a tsconfig.json file and add your custom settings i.e.:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "node",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src"]
}

• Create a tsup.config.ts file and add your custom settings i.e.:

import { defineConfig } from "tsup";
export default defineConfig({
  format: ["cjs", "esm"],
  entryPoints: ["src/index.ts"],
  dts: true,
  sourcemap: true,
  clean: true,
  skipNodeModulesBundle: true,
  shims: true,
});

• Configure scripts. For example:
• The build script will run the tsup command to transpile the TypeScript code to JavaScript.
• The prepublishOnly script will run the build script before publishing to npm.

{
  "scripts": {
    "build": "tsup",
    "prepublishOnly": "npm run build"
  }
}

• Add code to your index.ts and run npm run build this will create the dist folder with the transpiled code.
• Now you have the following files:
  • dist/index.js - CommonJS
  • dist/index.mjs - ESM
  • dist/index.d.ts - Types
  • dist/index.js.map - Source map for CommonJS
  • dist/index.mjs.map - Source map for ESM
  • dist/index.d.ts.map - Source map for Types

Writing your project - Setting up your project structure

• Figure out what the scope of your project and what will it be used for.

  • i.e. for this example we will give users the access to functions.
    • Create a functions.ts file that you can use to export your functions then import them in your index.ts file and export them from there.
    • User will destructure what they need from the package i.e. import { add, subtract } from 'publish-to-npm-template'
    • Create a types.ts file to export your types and interfaces. This will be used in your functions.ts file.
    • Create a test folder and add a functions.test.ts file to test your functions.
      • Add a test script to your package.json file to run your tests.
      • Add a jest configuration file to your project.
      • Add jest as a dev dependency.
        • Install jest and @types/jest as dev dependencies.
        • Create a jest.config.js file and add your custom settings.
      • How to test your functions:
        • Import your functions from your functions.ts file.
          • i.e. import { add, subtract } from '../src/functions'
          • Create your tests.
          • Run your tests with npm test.
        • Write your tests.
        • Run your tests with npm test.

• Create your gitignore file.

  • Add the following to your .gitignore file:

    /node_modules
    /dist
    .env
    .DS_Store

• Create .npmignore file to ignore files that you don't want to publish to npm.

  • Copy in what you have in your .gitignore file and make some changes

          /src
          /node_modules
          /test
          .env
          .DS_Store
          tsconfig.json
          tsup.config.tsconfig

• Add a README.md file to your project. This will be displayed on npm.

• Publish your package to npm.

  • Run npm publish to publish your package to npm.
  • Check your package on npm.
  • Update your package and increment the version number.
  • Run npm publish to publish your package to npm.
  • Check your package on npm.