1 | <h1 align="center">
|
2 | ts-deps
|
3 | <p align="center" style="font-size: 0.5em">
|
4 | <a href="https://www.npmjs.com/package/ts-deps">
|
5 | <img src="https://img.shields.io/npm/v/ts-deps.svg" >
|
6 | </a>
|
7 | <a href="https://travis-ci.com/zaripych/ts-deps">
|
8 | <img src="https://travis-ci.com/zaripych/ts-deps.svg?branch=master" alt="Travis Build Status">
|
9 | </a>
|
10 | <a href="https://codecov.io/gh/zaripych/ts-deps">
|
11 | <img src="https://codecov.io/gh/zaripych/ts-deps/branch/master/graph/badge.svg" />
|
12 | </a>
|
13 | <a href="https://greenkeeper.io/">
|
14 | <img src="https://badges.greenkeeper.io/zaripych/ts-deps.svg" />
|
15 | </a>
|
16 | </p>
|
17 | <p align="center">dev dependency for your simple TypeScript projects</p>
|
18 | </h1>
|
19 |
|
20 | ### Installation
|
21 |
|
22 | ```
|
23 | npm add ts-deps --save-dev
|
24 | npx ts-deps init
|
25 | ```
|
26 |
|
27 | The `init` command will scaffold config files for your project. The typical output would be:
|
28 |
|
29 | ```
|
30 | scripts/
|
31 | scripts/build.js
|
32 | scripts/clean.js
|
33 | scripts/combineCoverage.js
|
34 | src/
|
35 | src/__integration-tests__
|
36 | src/__tests__
|
37 | babel.config.js
|
38 | commitlint.config.js
|
39 | jest.config.integration.js
|
40 | jest.config.js
|
41 | package.json
|
42 | prettier.config.js
|
43 | release.config.js
|
44 | tsconfig.json
|
45 | tsconfig.declarations.json
|
46 | tslint.json
|
47 | ```
|
48 |
|
49 | Following packages already included for you:
|
50 |
|
51 | - babel - Babel 7 to build `.js` or `.ts` which brings more transformation options and speed
|
52 | - typescript - TypeScript used for type checking and declarations
|
53 | - jest - Jest uses same babel config as build pipeline
|
54 | - tslint
|
55 | - prettier https://prettier.io/
|
56 | - semantic-release https://github.com/semantic-release/semantic-release
|
57 | - husky
|
58 | - pretty-quick
|
59 | - commitlint https://conventional-changelog.github.io/commitlint
|
60 |
|
61 | The `init` command can be run on an existing project, it will change your `package.json` and remove superfluous dev dependencies.
|
62 |
|
63 | ### Building your code
|
64 |
|
65 | All the source code should be located in `src` directory. Extensions for the code should be `.ts` or `.js`.
|
66 | You can add `// @ts-check` in the beginning of `.js` files to make TypeScript check those files as well.
|
67 |
|
68 | For a Web app, please consider using `create-react-app`, however, `.tsx` and `.jsx` extensions are still allowed, but not well-tested.
|
69 |
|
70 | ```
|
71 | npm build
|
72 | ```
|
73 |
|
74 | The code will be transformed by Babel and put into `lib` folder. In addition to that `.json` and `.d.ts` files are copied over as well.
|
75 |
|
76 | ### Declarations
|
77 |
|
78 | If declarations are required, we can generate them by running:
|
79 |
|
80 | ```
|
81 | npm run declarations
|
82 | ```
|
83 |
|
84 | This will use `tsconfig.declarations.json` config to write declarations to the same `lib` folder as transformed `.js` or `.ts` files.
|
85 |
|
86 | ### Checking your code
|
87 |
|
88 | To run all builds and compilation checks we can use the `check` command which is automatically executed by husky on push.
|
89 |
|
90 | ```
|
91 | npm run check
|
92 | ```
|
93 |
|
94 | The `build` and other commands listed below are included into `check`.
|
95 |
|
96 | So, to check your code for Type Script errors we can run:
|
97 |
|
98 | ```
|
99 | npm run type-check
|
100 | ```
|
101 |
|
102 | Linting:
|
103 |
|
104 | ```
|
105 | npm run lint
|
106 | ```
|
107 |
|
108 | ### Aliases
|
109 |
|
110 | Current configuration supports aliases. Sometimes we need to be able to alias a path to a module in order to require it by that alias name like so:
|
111 |
|
112 | ```
|
113 | import { db } from '@shared'
|
114 | ```
|
115 |
|
116 | The above becomes possible with aliases. The setup of aliases is tedious and requires multiple configuration changes that span across Babel, TypeScript and Jest.
|
117 |
|
118 | With `ts-deps` it should be as simple as creating a `ts-deps.config.js` file at the root of your project and executing `ts-deps patch` to patch `tsconfig.json`:
|
119 |
|
120 | ```
|
121 | module.exports = {
|
122 | aliases: {
|
123 | '@core-lib': './src/shared/core-lib',
|
124 | '@feature-1': './src/shared/features/feature-1',
|
125 | },
|
126 | }
|
127 |
|
128 | ```
|
129 |
|
130 | In the above example, in order to reference files within `core-lib` directory we can just use:
|
131 |
|
132 | ```
|
133 | import Module from '@core-lib'
|
134 | ```
|
135 |
|
136 | That saves us from having to backward slash to that directory if we have a module in `feature-1` directory that requires it.
|
137 |
|
138 | ### Testing
|
139 |
|
140 | The library supports two categories of tests: _unit-tests_ and _integration-tests_.
|
141 |
|
142 | Unit tests should be located within `__tests__` directory anywhere under `src` directory. Deep nesting is supported. Every test should have `.test.` suffix. This is to ensure that the tests can also have test-only related helper files that can be required by the test but not included into result of `build`.
|
143 |
|
144 | Integration tests should be located within `./src/__integration-tests__` at the root. Similarly, every test should have `.test.` suffix.
|
145 |
|
146 | Integration and unit tests can be ran separately. If integration tests generate any coverage information we can combine it with unit tests using `combine-coverage` script.
|
147 |
|
148 | ```
|
149 | npm run test --coverage
|
150 | npm run integration --coverage
|
151 | npm run combine-coverage
|
152 | ```
|
153 |
|
154 | ### Release
|
155 |
|
156 | To use `semantic-release` for release process we could run:
|
157 |
|
158 | ```
|
159 | npm run release
|
160 | ```
|
161 |
|
162 | To setup follow the link at the top and follow the steps in documentation. With current config we only need to declare environment variables to make
|
163 | `semantic-release` push changes to GitHub Releases, git repo and npm.
|
164 |
|
165 | ```
|
166 | export GH_TOKEN=
|
167 | export NPM_TOKEN=
|
168 | export GIT_AUTHOR_EMAIL=
|
169 | export GIT_AUTHOR_NAME=
|
170 | export GIT_COMMITTER_EMAIL=
|
171 | export GIT_COMMITTER_NAME
|
172 | ```
|
173 |
|
174 | ### Happy coding!
|