Создаём библиотеку по последнему слову техники

Привет, Хабр. Это статья о том как написать Hello world по последнему слову техники.

В конце мы получим hello world библиотеку которая:

• Использует typescript
• Заботится о codestyle
• Генерирует доку
• Проводит тесты

Начало начал

В новой папке инициируем git и npm

 git init
 npm init

При настройке npm

 package name: (bestlibever) 
version: (1.0.0) 0.1.0
description: Best lib forever
entry point: (index.js) 
test command: jest
git repository: 
keywords: 
author: >MAX_ (maximmasterr)
license: (ISC) MIT

Структура проекта

В проекте будут следующие директории:

• src – Здесь будут лежать файлы самой библиотеки (typescript)
• lib – Сюда tsc положит скомпилированные файлы из src
• test – Здесь лежат тесты
• examples – Примеры использования

Также необходимо добавить в .gitignore:

lib/
node_modules/

Typescript

Теперь установим и настроим typescript:

npm i typescript -D

И создадим файл с именем tsconifg.json

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

Теперь сделаем основной файл лежащий src/index.ts

export function helloWorld(){
  return 'Hello world!'
}

Также добавим в package.json скрипты:

    "build": "tsc",
    "dev": "tsc --watch"

Теперь мы можем запустить разовое построение помощью:

npm run build

И многоразовое:

npm run dev

Codestyle

Для проверки стиля кода будем использовать tslint и prettier, а также запускать это перед коммитом.
Установим tslint, prettier, husky:

npm i tslint tslint-config-prettier prettier husky -D

Настроим prettier создав файл .prettierrc с содержимым

{
  "printWidth": 120,
  "trailingComma": "none",
  "singleQuote": true
}

Добавим скрипт для запуска prettier

    "prettier": "npx prettier --write src/* test/* example/*"

Настроим tslint создав файл tslint.json с содержимым

{
  "extends": ["tslint:recommended", "tslint-config-prettier"],
  "rules": {
    "curly": false,
    "ordered-imports": false,
    "interface-name": [true, "never-prefix"] 
  }
}

Добавляем скрипт tslint и codestyle:

    "tslint": "tslint -p tslint -p tsconfig.json",
    "codestyle": "npm run prettier && npm run tslint"

Теперь сделаем что бы перед коммитом запускался codestyle добавим в package.json:

"husky": {
  "hooks": {
    "pre-commit": "npm run codestyle"
  }
}

Документация

Для генерации веб страниц из md используем docsify и для генерации документации из api tsdoc

Установим их

npm i docsify-cli typedoc -D

В папке docs создадим README.md:

# Best lib ever
Best lib ever

`helloWorld` return `'hello world'`

## Example
``js
const a = require('')
console.log(a.helloWorld()) // prints 'Hello world!'
``

Также добавим moreExample.md
Исходник лежит здесь

Дальше выполните

npx docsify init ./docs

Настроим sidebar в docsify создав файл sidebar.md

# Best lib ever
*  [Best lib ever](/)
*  [More examples](/moreExamples)

Теперь, чтобы просмотреть всю эту красоту добавим скрипт

"docsify": "docsify serve ./docs"

И запустим

npm run docsify

Теперь займёмся статическим документирование методов
Для начала добавим описание функции в коде:

/**
 * Returns `Hello world!`
 */

В .gitinore добавим docs/api

Добавим скрипт для typedoc

"typedoc": "typedoc --out ./docs/api ./src --mode file --readme docs/README.md"

И наконец добавим финальный скрипт для доки

"docs": "npm run typedoc && npm run docsify"

Всё теперь для просмотра доки достаточно

npm run docs

Тесты

Установим jest

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

Создадим конфиг jest.config.js

module.exports  = {
  roots: ['/src'],
  transform: {
    '^.+\\.tsx?$':  'ts-jest',
  },
  testRegex:  '(/__test__/.*|(\\.|/)(test|spec))\\.tsx?$',
  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
}

Создадим тест(test/index.ts):

import { helloWorld } from  "../src";

test('Should return helloWorld', () => {
  expect(helloWorld()).toBe('Hello world!')
})

И теперь запуск тестов возможен по

npm test

Обобщим

Теперь мы можем

npm run build # Запустить построение
npm run dev # Запустить авто построение 
npm run codestyle # Проверка стиля кода
npm run docs # Посмотреть доку
npm test # Прогнать тесты

Финальный репозиторий github