Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jeremyben/tsc-prog
Create a tsconfig and compile Typescript files programmatically.
https://github.com/jeremyben/tsc-prog
bundling definitions tsc tsconfig typescript
Last synced: 5 days ago
JSON representation
Create a tsconfig and compile Typescript files programmatically.
- Host: GitHub
- URL: https://github.com/jeremyben/tsc-prog
- Owner: jeremyben
- License: mit
- Created: 2019-07-16T12:35:23.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-07-29T15:10:21.000Z (over 1 year ago)
- Last Synced: 2024-10-02T12:06:43.597Z (about 1 month ago)
- Topics: bundling, definitions, tsc, tsconfig, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/tsc-prog
- Size: 552 KB
- Stars: 51
- Watchers: 2
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.MD
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - tsc-prog
README
# `tsc-prog`
Build your TypeScript projects programmatically.
`tsc-prog` offers flexiblity and convenient options for your more complex production builds (less suited for development builds).
## Getting started
```bash
npm i -D tsc-prog
yarn add -D tsc-prog
```
_`tsc-prog` has no dependency. You just need typescript as a peer dependency._
### You simply need to build 👷
Use **`tsc.build`**. Specify the `basePath` first, and either inherit from a tsconfig file or create a config from scratch.
```js
const tsc = require('tsc-prog')
tsc.build({
basePath: __dirname, // always required, used for relative paths
configFilePath: 'tsconfig.json', // config to inherit from (optional)
compilerOptions: {
rootDir: 'src',
outDir: 'dist',
declaration: true,
skipLibCheck: true,
},
include: ['src/**/*'],
exclude: ['**/*.test.ts', '**/*.spec.ts'],
})
```
_You can have a look at all the parameters **[here](./src/interfaces.ts)**._
### You need more access 👨🏭
The `tsc.build` function is made of the two following steps, which you can have access to :
- [Program](https://github.com/microsoft/TypeScript/wiki/Architectural-Overview#data-structures) creation with **`tsc.createProgramFromConfig`**.
- Emitting files from program with **`tsc.emit`**.
```js
const tsc = require('tsc-prog')
// Create the program
const program = tsc.createProgramFromConfig({
basePath: process.cwd(),
configFilePath: 'tsconfig.json',
})
// Do what you want with the program
// Actually compile typescript files
tsc.emit(program, { copyOtherToOutDir: true })
```
## Addons
### Clean 🧹
_Helps to address [this issue](https://github.com/microsoft/TypeScript/issues/16057)._
We frequently need to delete the emitted files from a previous build, so a **`clean`** option recursively removes folders and files :
```js
tsc.build({
basePath: __dirname,
configFilePath: 'tsconfig.json',
clean: ['dist'], // accepts relative paths to `basePath` or absolute paths
})
```
You can also directly specify common targets from your compiler options :
```js
tsc.build({
basePath: __dirname,
configFilePath: 'tsconfig.json',
clean: { outDir: true, declarationDir: true },
})
```
###### Protections
The `clean` option protects you against deleting the following folders :
- the specified `basePath` and all its parents (up to the root folder).
- the current working directory and all its parents (up to the root folder).
- the `rootDir` path if specified in the compiler options and all its parents (up to the root folder).
### Copy non-typescript files 🗂️
_Helps to address [this issue](https://github.com/Microsoft/TypeScript/issues/30835)._
The **`copyOtherToOutDir`** option allows you to copy other files to `outDir` (well it says so) :
```js
tsc.build({
basePath: __dirname,
configFilePath: 'tsconfig.json',
compilerOptions: {
outDir: 'dist', // must be set
},
copyOtherToOutDir: true,
exclude: ['**/somedir'], // taken into account
})
```
This option is protected against overwriting files emitted by the compiler, like same name `.js` files (could happen).
### Bundle type definitions 🛍️
_Helps to address [this issue](https://github.com/microsoft/TypeScript/issues/4433)._
Rollup your emitted `.d.ts` files into a single one with **`bundleDeclaration`** option.
```js
tsc.build({
basePath: __dirname,
configFilePath: 'tsconfig.json',
compilerOptions: {
rootDir: 'src',
outDir: 'dist',
declaration: true // must be set
},
bundleDeclaration: {
entryPoint: 'index.d.ts', // relative to the OUTPUT directory ('dist' here)
},
})
```
#### Bundling options
```js
tsc.build({
// ...
bundleDeclaration: {
entryPoint: 'index.d.ts',
fallbackOnError: false, // default: true
globals: false // default: true
augmentations: false // default: true
}
})
```
- `fallbackOnError` option is a safety mecanism that generates the original unbundled definition files if any error happens during the bundling process.
- `globals` option can be switched to `false` to discard global declarations.
- `augmentations` option can be switched to `false` to discard external library augmentations.
#### Notes on bundling 🗣️
I recommend you still check the final `.d.ts` output, declaration bundling being very complex, with a lot of edge cases and issues such as name conflict and handling of external libraries.
`tsc-prog` does its best to acknowledge every edge case. It covers ones that similar tools don't and probably vice versa. Don't hesitate to review [API Extractor](https://api-extractor.com/) to see if it works better with your program.