| 1 | ## Introduction
|
| 2 |
|
| 3 | While you write TypeScript code, you want it to compile, tests to succeed,
|
| 4 | code coverage to be upheld and the code should conform to formatting and linting rules.
|
| 5 | There are already great tools that help you do this. But running them manually can be time-consuming.
|
| 6 |
|
| 7 | In order to be more productive, we ended up creating TypeScript Assistant, that takes care of running the right tools at the right time.
|
| 8 |
|
| 9 | - Before commit: Check formatting and linting
|
| 10 | - Before push: Compile, run unit test and check coverage
|
| 11 | - After pull: Update packages
|
| 12 |
|
| 13 | It also adds npm scripts to:
|
| 14 |
|
| 15 | - Fix formatting and linting (`npm run fix`)
|
| 16 | - Release to npm (`npm run release`)
|
| 17 | - Run all tools on save in the background (`npm run assist`)
|
| 18 | - Open code coverage (`npm run coverage-show`)
|
| 19 | - Run continuous integration (`npm run ci`)
|
| 20 | - Clean (`npm run clean`)
|
| 21 |
|
| 22 | Read about the philosophy behind TypeScript Assistant on [our blog](https://dev.afas.nl/blog-dev/typescript-assistant).
|
| 23 |
|
| 24 | ## Getting started
|
| 25 |
|
| 26 | You can try TypeScript Assistant on a new project by running
|
| 27 | ```
|
| 28 | git init && npm init && npm install typescript-assistant && ./node_modules/.bin/tsa init
|
| 29 | ```
|
| 30 |
|
| 31 | On existing TypeScript projects, you can just run
|
| 32 | ```
|
| 33 | npm install typescript-assistant && npm dedupe && ./node_modules/.bin/tsa init
|
| 34 | ```
|
| 35 |
|
| 36 | TypeScript Assistant will not overwrite any configuration you already have.
|
| 37 |
|
| 38 | ## Configuration
|
| 39 |
|
| 40 | Not everything is configurable in TypeScript Assistant.
|
| 41 |
|
| 42 | - `/dist` contains artifacts that get distributed in a release. It is excluded from source control.
|
| 43 | - `/build` contains build output and temporary artifacts. It is excluded from source control.
|
| 44 | - `/test` contains (unit)tests written in mocha
|
| 45 |
|
| 46 | TypeScript Assistant enforces \n as end-of-line on every platform.
|
| 47 | It does not have a configuration file of is own, it lets the underlying tools use their own configuration files.
|
| 48 | `tsa init` prepares these files as follows:
|
| 49 |
|
| 50 | - `.editorconfig` - End-of-line and tab size set to 2 spaces
|
| 51 | - `.gitattributes` - End-of-line
|
| 52 | - `.gitignore` - Exclude non-source files
|
| 53 | - `.npmignore` - Configure what gets packaged, only `/dist` and `README.md`
|
| 54 | - `package.json` - Adds scripts for git hooks and tasks provided by TypeScript Assistant. Also contains configuration for `nyc` (code coverage)
|
| 55 | - `src/tsconfig.json` - Strict TypeScript configuration for sources. Output is written to `/dist`
|
| 56 | - `tsconfig.json` - Lenient TypeScript configuration for unit tests, does not write output. (tests run fine using `ts-node`)
|
| 57 | - `tsfmt.json` - End-of-line and tab size
|
| 58 | - `tslint.json` - Contains the linting rules you prefer. By default it is set to inherit from the AFAS Software rules shipped by TypeScript Assistant. It can
|
| 59 | be modified to suit your needs
|
| 60 | - `tslint.editor.json` - Extends `tslint.json` and disables some rules to make your IDE (vscode/webstorm) easier to work with.
|
| 61 |
|
| 62 | The folder `/src` is assumed to contain source files, but this can be modified by changing the `tsconfig.json` files and the `nyc` section in `package.json`.
|
| 63 | All configuration files can be changed as needed.
|
| 64 |
|
| 65 | If you are creating a browser package, you can get inspiration from [maquette](https://maquettejs.org) on how you can put browser bundles in the `dist` folder
|
| 66 | using TypeScript
|
| 67 | Assistant.
|
| 68 | See the `dist` task in the [package.json](https://github.com/AFASSoftware/maquette/blob/master/package.json).
|
| 69 |
|
| 70 | ## NOTE
|
| 71 |
|
| 72 | When typescript-assistant cannot find some of its dependencies,
|
| 73 | it may be required to run `npm dedupe` which makes sure all required
|
| 74 | dependencies will be located directly under `node_modules` of your project
|
| 75 |
|
| 76 | ## Contributing
|
| 77 |
|
| 78 | We would love to discuss the best practices that TypeScript Assistant is meant to support.
|
| 79 | To start a discussion you may open an issue.
|
| 80 | We do not intend to make TypeScript Assistant ultimately flexible to support everyone's needs,
|
| 81 | but pull requests for improvements are welcome.
|