gem-hunter
Language: TypeScript
A Rollup Typescript Plugin with Reference Support
Using npm:
npm install rollup-typescript-plugin-projects --save-dev
Using yarn:
yarn add rollup-typescript-plugin-projects --dev
Create a rollup.config.js configuration file and import the plugin
import typescript from "rollup-typescript-plugin-projects" import { nodeResolve } from "@rollup/plugin-node-resolve"; import nodePolyfills from 'rollup-plugin-polyfill-node'; import commonjs from '@rollup/plugin-commonjs'; import css from "rollup-plugin-import-css"; import json from '@rollup/plugin-json'; export default { input: './src/index.ts', output: { dir: './dist', format: 'esm', preserveModules: true, preserveModulesRoot: '', sourcemap: true, }, plugins: [ typescript({ includeUnusedFiles: true // Can be toggled on to aggressivly load all files in the project }), css({output: "vendor.css"}), json(), commonjs(), nodePolyfills(), nodeResolve({ preferBuiltins: false }), ] }
Type: CompilerOptions
Default: null
Provides a global override for the TypeScript CompilerOptions. The projects option will override the settings even further if specific
customizations are needed for a single project.
Type: [key: string]: CompilerOptions
Default: null
Use the path of a TS config to modify that project's details. This can be used to greater control one specific projects configs.
Example:
"./project/tsconfig.json": { compilerOptions: { sourceMap: true, } }
Type: boolean
Default: null
Can be toggled on to force all files to be loaded into the TypescriptPlugin, even if it's not included as the src file in Rollup.
Type: boolean
Default: null
Can be toggled on to force .d.ts files not be generated. This is not standard multi-project build behaviour, but is often preferred when publishing projects.
You will need Rollup version 1.62.1 or later for this project to fully work as intended.
The below example is a website ready configuration using ESM module loading.
import typescript from "rollup-typescript-plugin-projects" import { nodeResolve } from "@rollup/plugin-node-resolve"; import nodePolyfills from 'rollup-plugin-polyfill-node'; import commonjs from '@rollup/plugin-commonjs'; import css from "rollup-plugin-import-css"; import json from '@rollup/plugin-json'; export default { input: './src/index.ts', output: { dir: './dist', format: 'esm', preserveModules: true, preserveModulesRoot: '', sourcemap: true, }, plugins: [ typescript({ includeUnusedFiles: true // Can be toggled on to aggressivly load all files in the project }), css({output: "vendor.css"}), json(), commonjs(), nodePolyfills(), nodeResolve({ preferBuiltins: false }), ] }
If bundling is preferred, the module configuration can be turned into the following to make as a single bundled file. Please be aware that includeUnusedFiles cannot be turned on if a single output is specified.
import typescript from "rollup-typescript-plugin-projects" import { nodeResolve } from "@rollup/plugin-node-resolve"; import nodePolyfills from 'rollup-plugin-polyfill-node'; import commonjs from '@rollup/plugin-commonjs'; import css from "rollup-plugin-import-css"; import json from '@rollup/plugin-json'; export default { input: './src/index.ts', output: { format: 'esm', sourcemap: true, file: 'bundle.js' }, plugins: [ typescript(), css({output: "vendor.css"}), json(), commonjs(), nodePolyfills(), nodeResolve({ preferBuiltins: false }), ] }
For typescript to compile, it's important to configure the project properly, especially when loading for multiple projects.
You may choose to override configs with either a global set of compilerOptions,
or you may choose to opt for a project specific config. Both configs may be used,
but the project config will override any setting set on the main compilerOptions.
The projects object accepts a config path (either relative or absolute) that will
then replace the existing projects settings when loaded.
export default { input: './src/index.ts', output: { format: 'esm', sourcemap: true, file: 'bundle.js' }, plugins: [ typescript({ compilerOptions: { removeComments: true }, projects: { "./tsconfig.json": { removeComments: false } } }), ] }
A typical project folder structure might look like the following:
- project
- config
- tsconfig.base.json # Shared
- packages
- project1
- IncludedFile.ts
- tsconfig.json
- src
- main.ts
- tsconfig.json
It's critical that all paths are under one single main project. You cannot have different configs with conflicting baseUrls.
You will want to create a shared config. This will be used to keep common details such as aliases. I have provided
an example below for the config/typescript/tsconfig.base.json
{
"compilerOptions": {
"composite": true,
"noEmit": false,
"paths": {
"@project1/*": ["packages/project1/*"],
"@main/*": ["src/*"]
}
}
}
On the root of a project, a main tsconfig should be configured. You can modify as desired, but it's critical that a baseUrl, rootDir, and outDir are provided. This helps with the compiler. I have not tested a non outDir based project, but it should work.
{
"extends": "./config/typescript/tsconfig.base.json",
"include": [
"src/*"
],
"compilerOptions": {
"module": "es2020",
"target": "es2020",
"strict": true,
"baseUrl": "./",
"rootDir": "./",
"outDir": "./build/"
},
"references": [
{
"path": "packages/project1"
}
]
}In the package project1, create another Typescript config file to handle its own configurations.
You can change project configs if necessary, but keeping them the same between projects should result in better
bundles.
{
"extends": "../../config/tsconfig.base.json",
"compilerOptions": {
"baseUrl": "../../",
"rootDir": "../../",
"outDir": "../../build/",
"module": "es2020",
"target": "es2020"
},
"include": ["."]
}If you want to see what a multi-project config can look like, take a look at the test fixtures labeled mutli-project inside this repository.
To build this project you can run yarn install. You may run the following yarn commands for this project
yarn build Will build the project onceyarn watch Will build, then watch future file changesyarn test Will run the jest test casesyarn test-coverage Will run the jest tests and provide a coverage report in the project folder.If you want to link this project to your existing project, you can use yarn link which will create a symlink
between the two projects.
yarn link inside the rollup-typescript-plugin-projects project. This should create a message saying the project link and how to symlinkyarn link rollup-typescript-plugin-projects which will link the project together.