@lengz/npm-typescript-greeter

Boilerplate for npm package with typescript

Usage no npm install needed!

<script type="module">
  import lengzNpmTypescriptGreeter from 'https://cdn.skypack.dev/@lengz/npm-typescript-greeter';
</script>

README

npm-typescript-greeter

Boilerplate for npm package with typescript

Manual Setup

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"
      }
    }
    
Script Description
start developing in watch mode
build build your project

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?quot;: "ts-jest"
      },
      "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)quot;,
      "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"
  }
}
Script Description
prepare prepare will run both BEFORE the package is packed and published, and on local npm install.
prepublishOnly prepublishOnly will run BEFORE prepare and ONLY on npm publish.
preversion preversion will run before bumping a new package version.
version Version will run after a new version has been bumped.
postversion Postversion will run after the commit has been made.

12. Finish package.json

{
  "name": "my-package",
  "description": "A nice greeter",
  "main": "lib/index.js",
  "types": "lib/index.d.ts"
}
Script Description
name your package name, it will show in npm
description about your package
main tell npm where it can import the modules from
types tell Typescript and Code-editors where can find the type definitions

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"
  }
}
Script Description
start developing in watch mode
build build your project
format format your code by prettier
lint run tslint
commit
test run unit test
prepare prepare will run both BEFORE the package is packed and published, and on local npm install.
prepublishOnly prepublishOnly will run BEFORE prepare and ONLY on npm publish.
preversion preversion will run before bumping a new package version.
version Version will run after a new version has been bumped.
postversion Postversion will run after the commit has been made.
bump-version bump a new patch version of the package
publish-public publishing a public scoped package