Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/barinbritva/init-typescript-app
Initialize clean TypeScript setup by running single command. Optional package publication to npm.
https://github.com/barinbritva/init-typescript-app
bolierplate build-tool package-creation starter-kit typescript zero-configuration
Last synced: 19 days ago
JSON representation
Initialize clean TypeScript setup by running single command. Optional package publication to npm.
- Host: GitHub
- URL: https://github.com/barinbritva/init-typescript-app
- Owner: barinbritva
- License: mit
- Created: 2020-03-18T11:03:26.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-06-16T13:22:37.000Z (5 months ago)
- Last Synced: 2024-10-11T15:11:26.163Z (about 1 month ago)
- Topics: bolierplate, build-tool, package-creation, starter-kit, typescript, zero-configuration
- Language: TypeScript
- Homepage:
- Size: 441 KB
- Stars: 25
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Init TypeScript App
[](https://github.com/barinbritva/init-typescript-app/blob/master/LICENSE)
## 🌟 Motivation
You are in the right repo if you want to:
* quickly get pure, technology agnostic `TypeScript` setup for further customization;
* easily create your own `npm` package.
## 📦 Features
* **Clean setup.** No dependencies. Only configured TypeScript with `production` and `development` build modes;
* **Tune compiler strictness.** Choose `base mode` to get TypeScript basic functionality or `advanced mode` to enable all kinds of checks;
* **Easy publication _(optional)_.** No more fuss with package publication to `npm`;
* **More features soon.** Please, read about upcoming features in [roadmap](#-roadmap) section.
## 🚀 Launch your project
### Quick overview
```sh
npx init-typescript-app
# then answer for a few questions in cli
cd project-name
npm install
npm run build
npm start
```
You are all set up!
You are also able to install `init-typescript-app` globally if you are using `npm` of version lower than `5.2.0`.
_In the documentation we always use `npm` in all examples to be short. Of course, you can use any of package managers `npm` or `yarn`._
### Starting in development mode
For development purposes it's reasonable to use `npm run build:dev` command. It does the following:
* Runs build process in `watch` mode and generates `source maps` files
* Disables a few compiler options for more comfortable developing process. See the details below.
Production settings include `"noUnusedLocals": true` and `"allowUnreachableCode": false` flags. That may be not really convenient. Consider next piece of pseudo code which is totally OK in terms of compiler:
```typescript
function doMyStuff (): number {
const numberOne: number = Math.random()
const numberTwo: number = Math.random()
const difference: number = numberOne - numberTwo
const anotherVariable: number = Math.random()
if (difference > 0) {
console.log(anotherVariable)
return numberOne
} else {
return numberTwo
}
}
```
It's common practice to comment and add some lines of code during development process. Let's change the code like this:
```typescript
function doMyStuff (): number {
const numberOne: number = Math.random()
const numberTwo: number = Math.random()
const difference: number = numberOne - numberTwo
// this line emits error by noUnusedLocals rule
const anotherVariable: number = Math.random()
console.log(numberOne, numberTwo)
return 1
// this block emits by allowUnreachableCode rule
if (difference > 0) {
// console.log(anotherVariable)
return numberOne
} else {
return numberTwo
}
}
```
That's why these checks are switched off for development. You won't get these errors in your build, but an IDE will still show you errors so that you don't forget to fix them. This is a really convenient approach.
## 📮 Publish your package
If you chose `npm package` as your project type, you can make your package publication happen by running one command.
_Just run `npm run release` from the root directory of your project. That's it!_
Before you start, please, check out next information in this section.
### Check your git setup
To use publication features it's necessary for your project to be a `git` repository.
```sh
# create empty repository at GitHub
# run from your project root directory:
git init
git remote add origin [email protected]:user-name/project-name.git
git push -u origin master
```
_This example uses `ssh` connection to communicate with a repository. If you haven't `ssh` setup yet you can [follow the instructions](https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account) to deal with it. You still can use `https` connection instead:_
```sh
git remote add origin https://github.com/user-name/project-name.git
```
### Check your npm setup
To publish your package it's necessary to be signed in via your [`npm`](https://www.npmjs.com/) account in your console. Create an account if you don't have it. Then auth from your console by [`npm login`](https://docs.npmjs.com/cli-commands/adduser.html) command.
_Of course, you can use any package registry you want, e.g. `npm.pkg.github.com`._
### Check your files
It's necessary to be sure you publish what you exactly mean to publish. Using `.npmignore` is antipattern (you can read more information about it [here](https://medium.com/@jdxcode/for-the-love-of-god-dont-use-npmignore-f93c08909d8d) and [here](https://blog.npmjs.org/post/165769683050/publishing-what-you-mean-to-publish)). By default, only next files will be included into your package:
```
# your built files, included via package.json
dist
# next files are included by npm by default:
package.json
README.md (and its variants)
CHANGELOG.md (and its variants)
LICENSE
```
If you add new files or directories, it's necessary to include them to [`files`](https://docs.npmjs.com/files/package.json#files) section of your `package.json`. Run `npm pack` and check out output tarball before release.
_More information about it and other helpful development techniques you can read in [npm developer guide](https://docs.npmjs.com/misc/developers)._
#### How publication works under the hood
The release script does next:
* Checks your working directory is clean in terms of Git. Commit or stash your changes before release.
* Builds your package
* Creates git tag with current version
* Publish the package to `npm` registry
* Increase version in `package.json`(and `package-lock.json` too) to next `patch` version
* Commit changes of `package*.json` files
* Push the new commit and tag to your repository
Ok! You are ready to work on the next version!
## 💡 Tips and tricks
### Customization
Have no concerns to change everything you need for your project. After once you run `init-typescript-app` you fully control your project. It's ok to edit `tsconfig.json` options or even change `build` or `release` scripts. Just a few examples what you may want to change:
* Pass change some params to build process or add extra steps to it
* Change your publication process to push the package for `private` access instead of `public`. To do that remove `--access public` from publish command in `release.sh`
* Change bumping commit text
_In other words, follow your goals!_
### Troubleshooting
* In rare cases it's possible to get errors from somewhere of `node_modules/**/*d.ts`. It means some third-party library typings are broken. If you run into this problem you can solve it by adding `"skipDefaultLibCheck": true` to `compilerOptions` of `tsconfig.json`. _More information about `tsconfig` will be available soon._
* If you chose `advanced` type checking, but run into the wall with it, you can rollback to `base` mode in two ways. The first way is to open `tsconfig.json` and invert a value of numerous options listed under `// Checks` comment. You can use hints from an IDE to detect exactly which options give you troubles. You are also able to toggle values one by one to find issuer. You can return toggled values when you will become more experienced. The second way is to permanently remove all the flags under `// Checks` comment.
* It's possible to face a situation when you will get an error when trying to use some default object like `window`, `document`, `Promise` or some operators. It means you have to include library's build-in typings to your `tsconfig`. [List of allowed libraries](https://www.typescriptlang.org/tsconfig#lib) you can find here. Current example looks like that:
```json
{
"compilerOptions": {
"lib": [
"DOM",
"ES2015"
]
}
}
```
* Sometimes it's necessary to extend definitions of standard objects. For instance, you use some library which adds custom property to `window` object - `window.customProperty`. Global `window` object always refers to build-in interface `Window` placed in `lib.dom.d.ts`. So you can't redeclare or edit it somehow. There are a lot of similar situations. Declaration merging comes to the rescue. The approach allows you to extend standard definitions implicitly. You can read more about [`declaration merging`](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) in the official documentation. Just one example to be clear:
```
// go to your project root dir
// create directory for types, for example `definitions`
// inside of `definitions` folder create file `dom.d.ts`
// add path `./definitions/dom.d.ts` to `include` section of your `tsconfg.json`
```
```json
{
"include": [
"./src",
"./definitions/dom.d.ts"
]
}
```
```
// for situation above add next code:
```
```typescript
interface Window {
// describe what you need
customProperty: Object;
}
```
## 🗺 Roadmap
### In version `1.x`
* **Tests.** Test frameworks, code coverage.
* **Code standards.** Setting up `eslint`, auto code formatting.
* **Pull-request bots.** Checking code coverage, dependencies vulnerabilities, etc
* **Changelog.** Documenting changes, integration with release process.
* **Webpack option.** Ability to make builds with Webpack.
* **Gulp option.** Running additional tasks.
### In version `2.x`
* **Applications templates.** Create not only libraries, but frontend and backend applications too.
## 🔙 Feedback
Your feedback is really important for the project. Please, use contacts from [my profile](https://github.com/barinbritva) to send your questions, suggestions, help requests and others. Also, feel free to use [issues](https://github.com/barinbritva/init-typescript-app/issues) section to report bugs and problems.
## 👛 Contributing
See [CONTRIBUTING](https://github.com/barinbritva/init-typescript-app/blob/master/CONTRIBUTING.md)
## 📄 License
MIT, see [LICENSE](https://github.com/barinbritva/init-typescript-app/blob/master/LICENSE) for the details.