@lengz/npm-typescript-greeter v1.0.2

npm-typescript-greeter

Boilerplate for npm package with typescript

Manual Setup

• 1. Create Package Folder
• 2. Create a git repository
• 3. Init npm Package
• 4. Install typescript
• 5. Formatting and Linting
• 6. Setup git hook
• 7. Your Greeter
• 8. ignore build folder
• 9. Unit Test
• 10. Write Unit Test
• 11. Add userfull npm scripts
• 12. Finish package.json
• 13. Push to repository
• 14. Publish package to NPM
• 15. Bumping a new version
• 16. Publishing a Scoped Package

npm scripts

Manual Setup

1. Create Package Folder

mkdir my-package
cd my-package

2. Create a git repository

• init

  git init
  echo "# My Package" >> README.md

• add .gitignore

  touch .gitignore

  copy ignore data into .gitignore from Node.gitignore

• push to your git repository

  git remote add origin <Git Repository Url>
  git push -u origin master

  Replace <Git Repository Url> to be the remote repository url

3. Init npm Package

npm init --y

4. Install typescript

• install as DevDependency

  npm install --save-dev typescript

• init tsconfig

  tsc --init

• modify .tsconfig.json

  {
    "compilerOptions": {
      "target": "es5",
      "module": "commonjs",
      "declaration": true,
      "outDir": "./lib",
      "strict": true
    },
    "include": ["src"],
    "exclude": ["node_modules", "**/__tests__/*"]
  }

  Option	Description
  target	We want to compile to es5 since we want to build a package with browser compatibility.
  module	Use commonjs for compatibility.
  declaration	When you building packages, this should be true. Typescript will then also export type definitions together with the compiled javascript code so the package can be used with both Typescript and Javascript.
  outDir	The javascript will be compiled to the lib folder.
  include	All source files in the src folder
  exclude	We don’t want to transpile node_modules, neither tests since these are only used during development.

5. Formatting and Linting

• install prettier, tslint, and tslint-config-prettier as DevDependency

  npm install --save-dev prettier tslint tslint-config-prettier

• create tslint.json

  {
    "extends": ["tslint:recommended", "tslint-config-prettier"],
    "rules": {
      "no-console": false,
      "object-literal-sort-keys": false,
      "member-access": false,
      "ordered-imports": false
    },
    "linterOptions": {
      "exclude": ["**/*.json", "node_modules"]
    }
  }

• create .prettierrc

  {
    "trailingComma": "all",
    "tabWidth": 4,
    "semi": false,
    "singleQuote": true,
    "endOfLine": "lf",
    "printWidth": 120,
    "overrides": [
      {
        "files": ["*.md", "*.json", "*.yml", "*.yaml"],
        "options": {
          "tabWidth": 2
        }
      }
    ]
  }

• create .editorconfig

  # EditorConfig is awesome: https://EditorConfig.org
  
  # top-most EditorConfig file
  root = true
  
  # Unix-style newlines with a newline ending every file
  [*]
  end_of_line = lf
  insert_final_newline = true
  charset = utf-8
  indent_style = space
  indent_size = 4
  
  [{*.json,*.md,*.yml,*.*rc}]
  indent_style = space
  indent_size = 2

• add npm scripts

  {
    "scripts": {
      "format": "prettier --write \"src/**/*.ts\" \"src/**/*.js\"",
      "lint": "tslint -p tsconfig.json"
    }
  }

  Script	Description
  format	format your code by prettier
  lint	run tslint

6. Setup git hook

Hook will run npm test before git commit and git push

• install

npm install --save-dev husky @commitlint/config-conventional @commitlint/cli commitizen cz-conventional-changelog

• create commitlint.config.js

  module.exports = {
    extends: ["@commitlint/config-conventional"]
  };

• create .huskyrc

  {
    "hooks": {
      "pre-commit": "npm run format && npm run lint && npm test",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }

• create .czrc

  { "path": "cz-conventional-changelog" }

• add npm scripts

  {
    "scripts": {
      "commit": "git-cz"
    }
  }

7. Your Greeter

cd my-package
mkdir src
cd src touch index.ts

• index.ts

  export const Greeter = (name: string) => `Hello ${name}`;

• add npm scripts

  {
    "scripts": {
      "start": "tsc -w",
      "build": "tsc"
    }
  }

8. ignore build folder

After npm build or npm start, /lib will be generated

add /lib to .gitignore

9. Unit Test

• install as DevDependency

npm install --save-dev jest ts-jest @types/jest

• create jestconfig.json

  {
    "transform": {
      "^.+\\.(t|j)sx?$": "ts-jest"
    },
    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
    "moduleFileExtensions": ["ts", "tsx", "js", "jsx", "json", "node"]
  }

• add npm scripts

  {
    "scripts": {
      "test": "jest --config jestconfig.json"
    }
  }

  Script	Description
  test	run unit test

10. Write Unit Test

• add __tests__ folder into src for unit test files, and add Greeter.test.ts

  import { Greeter } from "../index";
  test("My Greeter", () => {
    expect(Greeter("Carl")).toBe("Hello Carl");
  });

• run test

  npm test

11. Add userfull npm scripts

{
  "scripts": {
    "prepare": "npm run build",
    "prepublishOnly": "npm test && npm run lint",
    "preversion": "npm run lint",
    "version": "npm run format && git add -A src",
    "postversion": "git push && git push --tags"
  }
}

12. Finish package.json

{
  "name": "my-package",
  "description": "A nice greeter",
  "main": "lib/index.js",
  "types": "lib/index.d.ts"
}

13. Push to repository

git add .
git commit -m "feat: init"
git push

14. Publish package to NPM

• create an NPM account

  signup at website https://www.npmjs.com/signup

  or rum command npm adduser

• login to NPM

  npm login

• publish to NPM

  npm publish

  prepare -> lint -> prepublishOnly

15. Bumping a new version

npm version patch

npm publish

16. Publishing a Scoped Package

• Creating a New Scoped Package

  npm init --scope=<org_scope>

  @org_scope/<pkg_name>

• Publishing a Private Scoped Package

  npm publish

• Publishing a Public Scoped Package

  npm publish --access public

npm scripts

{
  "scripts": {
    "start": "tsc -w",
    "build": "tsc",
    "format": "prettier --write \"src/**/*.ts\" \"src/**/*.js\"",
    "lint": "tslint -p tsconfig.json",
    "commit": "git-cz",
    "test": "jest --config jestconfig.json",
    "prepare": "npm run build",
    "prepublishOnly": "npm test && npm run lint",
    "preversion": "npm run lint",
    "version": "npm run format && git add -A src",
    "postversion": "git push && git push --tags",
    "bump-version": "npm version patch",
    "publish-public": "npm publish --access public"
  }
}