{"id":13660506,"url":"https://github.com/jeremyben/tsc-prog","last_synced_at":"2025-04-05T08:31:04.434Z","repository":{"id":35021513,"uuid":"197190920","full_name":"jeremyben/tsc-prog","owner":"jeremyben","description":"Create a tsconfig and compile Typescript files programmatically.","archived":false,"fork":false,"pushed_at":"2023-07-29T15:10:21.000Z","size":565,"stargazers_count":51,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-02T12:06:43.597Z","etag":null,"topics":["bundling","definitions","tsc","tsconfig","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/tsc-prog","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeremyben.png","metadata":{"files":{"readme":"README.MD","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-07-16T12:35:23.000Z","updated_at":"2024-02-29T03:23:19.000Z","dependencies_parsed_at":"2024-01-07T21:16:38.920Z","dependency_job_id":null,"html_url":"https://github.com/jeremyben/tsc-prog","commit_stats":{"total_commits":72,"total_committers":2,"mean_commits":36.0,"dds":"0.16666666666666663","last_synced_commit":"fedd99e1e07df06dd394b44b36f5d9c6dba4afa0"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":"jeremyben/node-typescript-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyben%2Ftsc-prog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyben%2Ftsc-prog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyben%2Ftsc-prog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyben%2Ftsc-prog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeremyben","download_url":"https://codeload.github.com/jeremyben/tsc-prog/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222736939,"owners_count":17030839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bundling","definitions","tsc","tsconfig","typescript"],"created_at":"2024-08-02T05:01:22.374Z","updated_at":"2024-11-05T13:19:11.474Z","avatar_url":"https://github.com/jeremyben.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# `tsc-prog`\n\nBuild your TypeScript projects programmatically.\n\n`tsc-prog` offers flexiblity and convenient options for your more complex production builds (less suited for development builds).\n\n## Getting started\n\n```bash\nnpm i -D tsc-prog\nyarn add -D tsc-prog\n```\n\n_`tsc-prog` has no dependency. You just need typescript as a peer dependency._\n\n### You simply need to build 👷‍\n\nUse **`tsc.build`**. Specify the `basePath` first, and either inherit from a tsconfig file or create a config from scratch.\n\n```js\nconst tsc = require('tsc-prog')\n\ntsc.build({\n\tbasePath: __dirname, // always required, used for relative paths\n\tconfigFilePath: 'tsconfig.json', // config to inherit from (optional)\n\tcompilerOptions: {\n\t\trootDir: 'src',\n\t\toutDir: 'dist',\n\t\tdeclaration: true,\n\t\tskipLibCheck: true,\n\t},\n\tinclude: ['src/**/*'],\n\texclude: ['**/*.test.ts', '**/*.spec.ts'],\n})\n```\n\n_You can have a look at all the parameters **[here](./src/interfaces.ts)**._\n\n### You need more access 👨‍🏭\n\nThe `tsc.build` function is made of the two following steps, which you can have access to :\n\n- [Program](https://github.com/microsoft/TypeScript/wiki/Architectural-Overview#data-structures) creation with **`tsc.createProgramFromConfig`**.\n- Emitting files from program with **`tsc.emit`**.\n\n```js\nconst tsc = require('tsc-prog')\n\n// Create the program\nconst program = tsc.createProgramFromConfig({\n\tbasePath: process.cwd(),\n\tconfigFilePath: 'tsconfig.json',\n})\n\n// Do what you want with the program\n\n// Actually compile typescript files\ntsc.emit(program, { copyOtherToOutDir: true })\n```\n\n## Addons\n\n### Clean 🧹\n\n_Helps to address [this issue](https://github.com/microsoft/TypeScript/issues/16057)._\n\nWe frequently need to delete the emitted files from a previous build, so a **`clean`** option recursively removes folders and files :\n\n```js\ntsc.build({\n\tbasePath: __dirname,\n\tconfigFilePath: 'tsconfig.json',\n\tclean: ['dist'], // accepts relative paths to `basePath` or absolute paths\n})\n```\n\nYou can also directly specify common targets from your compiler options :\n\n```js\ntsc.build({\n\tbasePath: __dirname,\n\tconfigFilePath: 'tsconfig.json',\n\tclean: { outDir: true, declarationDir: true },\n})\n```\n\n###### Protections\n\nThe `clean` option protects you against deleting the following folders :\n\n- the specified `basePath` and all its parents (up to the root folder).\n- the current working directory and all its parents (up to the root folder).\n- the `rootDir` path if specified in the compiler options and all its parents (up to the root folder).\n\n### Copy non-typescript files 🗂️\n\n_Helps to address [this issue](https://github.com/Microsoft/TypeScript/issues/30835)._\n\nThe **`copyOtherToOutDir`** option allows you to copy other files to `outDir` (well it says so) :\n\n```js\ntsc.build({\n\tbasePath: __dirname,\n\tconfigFilePath: 'tsconfig.json',\n\tcompilerOptions: {\n\t\toutDir: 'dist', // must be set\n\t},\n\tcopyOtherToOutDir: true,\n\texclude: ['**/somedir'], // taken into account\n})\n```\n\nThis option is protected against overwriting files emitted by the compiler, like same name `.js` files (could happen).\n\n### Bundle type definitions 🛍️\n\n_Helps to address [this issue](https://github.com/microsoft/TypeScript/issues/4433)._\n\nRollup your emitted `.d.ts` files into a single one with **`bundleDeclaration`** option.\n\n```js\ntsc.build({\n\tbasePath: __dirname,\n\tconfigFilePath: 'tsconfig.json',\n\tcompilerOptions: {\n\t\trootDir: 'src',\n\t\toutDir: 'dist',\n\t\tdeclaration: true // must be set\n\t},\n\tbundleDeclaration: {\n\t\tentryPoint: 'index.d.ts', // relative to the OUTPUT directory ('dist' here)\n\t},\n})\n```\n\n#### Bundling options\n\n```js\ntsc.build({\n\t// ...\n\tbundleDeclaration: {\n\t\tentryPoint: 'index.d.ts',\n\t\tfallbackOnError: false, // default: true\n\t\tglobals: false // default: true\n\t\taugmentations: false // default: true\n\t}\n})\n```\n\n- `fallbackOnError` option is a safety mecanism that generates the original unbundled definition files if any error happens during the bundling process.\n\n- `globals` option can be switched to `false` to discard global declarations.\n\n- `augmentations` option can be switched to `false` to discard external library augmentations.\n\n#### Notes on bundling 🗣️\n\nI 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.\n\n`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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremyben%2Ftsc-prog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeremyben%2Ftsc-prog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremyben%2Ftsc-prog/lists"}