This package has been deprecated

Author message:

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

typescript-dev-kit

Build any JavaScript or TypeScript project in minutes, without worrying about the configuration.

Table of Contents

1. Philosophy
2. Features
3. Installation
4. Configuration
   1. The Easy Way
   2. The (less) Easy Way
5. Usage
6. Contributing
7. Sponsor
8. Maintainers
9. License

Philosophy

Most JS/TS development environments out there are often completely opinionated (i.e. meant to build exclusively React, Vue, or Svelte apps). It can be very frustrating when developing cross-frameworks solutions, or dealing with multiple stacks.

Also, managing and maintaining dozens of similar configuration (.eslintrc, .babelrc, webpack.config.dev.js, tsconfig.json, .npmrc, the list is endless) files over your projects is an unecessary, time-consuming task. Most of the time, configuration are exactly the same, they bloat your repositories, and impacts projects structuration/legibility.

That's precisely why typescript-dev-kit is here. It aims to provide:

• A nice, simple, performant development experience
• A 0-configuration (but still flexible) flow, with no setup headaches
• A framework-agnostic setup, allowing you to develop either for front or back ends, or even libraries to publish over NPM
• An all-included environment, with shipped-in unit-testing solution, linter, bundler, optimizations, transpiler, ...

Features

This toolbox includes:

• Unit testing solution: with vitest (which is the best JS/TS testing framework on the market)
• Optimized bundling: with esbuild and vite (the most complete and performant bundlers to date)
• Bundle analyser: with Rollup Plugin Visualizer
• Coverage reporting: with C8
• Automated documentation generation: with TypeDoc
• TypeScript support
• SASS support
• Dynamic imports support
• Sourcemaps generation
• index.html generation from template
• React / Svelte / Vue support: with Svelte / Vue Single File Components
• Code Linting: based on Airbnb Style Guide
• Hot Module Reloading when developing front-end solutions
• Automatic package bundling: if you are writing a NPM package
• Node 16+ / Evergreen browsers support: with ES7 features and Autoprefixer
• Environment initialization command

Installation

yarn add --dev typescript-dev-kit

Configuration

Note: Your project must be ESM-compatible ("type": "module" in your package.json).

The easy way

You can pick-up one of the boilerplates that are available on project-boilerplate, depending on your needs (based on Docker). No configuration required, you're aleady good to go!

The (less) easy way

If you prefer setting up your project from scratch without using an existing boilerplate, here are the files you need to change in order to unleash the full power of typescript-dev-kit.

Add the following to your package.json:

...
"tsDevKitConfig": {
  "target": "node",     // Can be "node" (back-end projects or libraries) or "web" (front-end projects).
  "devServer": {        // Your dev server configuration (front-end projects).
    "host": "0.0.0.0",
    "port": 3000
  },
  "html": "./html/index.html" // Your index.html template configuration (front-end projects).
  "runInDev": true,           // Whether to launch main entrypoint with node after each compilation in dev mode (back-end projects).
  "splitChunks": true,        // Whether to split JS chunks, or bundle everything in 1 file in build mode.
  "entries": {                // Here you can list all your entrypoints (relative paths from your "srcPath").
    "main": "main.ts",
    "other": "otherScript.js",
    ...
  },
  "srcPath": "src",     // Source path, containing your codebase.
  "distPath": "public", // Distribution path, in which all assets will be compiled.
  "publicPath": "https://assets.dev", // URL from which assets will be fetched (front-end projects).
  "banner": "/*! Copyright John Doe. */", // This banner will be put at the top of all your bundled assets.
  "env": {              // Set your environment variables if necessary, they will be automatically inserted in the code at build time (front-end projects).
    "development": {
      "NODE_ENV": "development",
      "API": "http://dev.api.com",
      ...
    },
    "production": {
      "NODE_ENV": "production",
      "API": "http://api.com",
      ...
    }
  },
  ...
  "scripts": {
    "init": "node_modules/typescript-dev-kit/scripts/init",
    "test": "cd node_modules/typescript-dev-kit && scripts/test",
    "dev": "cd node_modules/typescript-dev-kit && node scripts/dev",
    "build": "cd node_modules/typescript-dev-kit && node scripts/build",
    "check": "cd node_modules/typescript-dev-kit && node scripts/check -f",
    "doc": "typedoc --out ./doc/ --exclude \"**/*.js\" --exclude \"**/__+(tests|mocks)__/**\" src/",
    "postinstall": "rm -f node_modules/.eslintcache"
  }
},
...
"eslintConfig": {       // Includes the shipped-in Eslint config (you can also override some rules if you want).
  "extends": [
    "./node_modules/typescript-dev-kit/main.cjs"
  ]
},

If you wish to develop in TypeScript, you need to create the following tsconfig.json file:

{
  "extends": "./node_modules/typescript-dev-kit/tsconfig.json",
  "compilerOptions": {
    "baseUrl": "src"    // Must be the same as your `package.json`'s "srcPath".
  }
}

/!\ Depending on the type of project you're developing, you might also want to add the "type": "module" directive in your package.json.

Usage

Project initialization

yarn run init

This script will initialize your project, populating metadata where they belong (authors/contributors, project name, git repository, ...).

Development mode

yarn run dev

Starts the development mode. In this mode, you benefit of the HMR on your pages (front-end projects) and automatic restart of your scripts (back-end project). This allows you to see your changes in real time. Final bundle isn't optimized to provide maximum responsiveness of the environment.

Note: when developing a library ("target": "node"), a random semver-compliant number is set in place of your package.json's version in the distributable directory. It allows you to test your package in real time by forcing cache invalidation.

Note: when developing a web app ("target": "web"), the index.html served by the development web server will be generated from the template you specified in your configuration, and will be kept in memory (not written on disk) for performance purpose.

Testing mode

yarn run test [-w]

Starts the testing mode. All your tests written in *.test.js(x) / *.test.ts(x) files are run, and code coverage report is generated at the end of the whole testing suite, in a coverage directory. The -w option allows you to run Jest in watch mode.

Build mode

yarn run build

Starts the build mode. You can pass the --force option to prevent pipe from failing in case of linting / typechecking issues. This mode bundles and optimizes your codebase and related assets for distribution. Sourcemaps are also generated (use --enable-source-maps to leverage on sourcemaps in Node), as well as the bundle analysis report in a report.html file. When building a NPM package, any relevant file (README.md, LICENSE, ...) is also included in your distributable directory.

Checking

yarn run check

Runs linter and type-checkers on your codebase. You can pass the -w option to enable watch mode, and -f to automatically fix issues when possible.

Documentation

yarn run doc

Generates an automatic technical documentation based on the comments and typings present in your code. The result is available in the doc directory.

Contributing

You're free to contribute to this project by submitting issues and/or pull requests. For more information, please read the Contribution guide.

Sponsor

Love this project and want to support it? You can buy me a coffee :)

Or just sending me a quick message saying "Thanks" is also very gratifying, and keeps me motivated to maintain open-source projects I work on!

Maintainers

Matthieu Jabbour

License

MIT

Copyright (c) Openizr. All Rights Reserved.