{"id":14984,"library":"ts-config-single-spa","title":"single-spa TypeScript Configuration","description":"ts-config-single-spa provides a foundational TypeScript configuration preset designed specifically for projects within the single-spa microfrontend ecosystem. Currently at version 3.0.0, this package aims to standardize `tsconfig.json` settings, ensuring compatibility and best practices across various microfrontends. It handles common configurations such as `target`, `module`, `jsx` support, and `moduleResolution`, which are critical for smooth integration in a polyglot microfrontend architecture. While there isn't a strict independent release cadence, it is part of the larger `create-single-spa` monorepo and updates are coordinated with other single-spa tooling, ensuring ongoing relevance and support. Its key differentiator is simplifying TypeScript setup for single-spa, minimizing boilerplate, and reducing common configuration pitfalls associated with module interoperation and shared dependencies in a microfrontend environment.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/single-spa/create-single-spa","tags":["javascript","single-spa","microfrontends","typescript"],"install":[{"cmd":"npm install ts-config-single-spa","lang":"bash","label":"npm"},{"cmd":"yarn add ts-config-single-spa","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-config-single-spa","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for TypeScript compilation. The preset relies on specific TypeScript compiler features.","package":"typescript","optional":false}],"imports":[{"note":"This package is a TypeScript configuration preset and is integrated via the `extends` property in your project's `tsconfig.json` file. It does not export any JavaScript/TypeScript symbols for direct `import` or `require`.","wrong":"import 'ts-config-single-spa';","symbol":"TsConfigExtends","correct":"{ \"extends\": \"ts-config-single-spa\" }"},{"note":"While `ts-config-single-spa` defines a set of `compilerOptions`, you do not import them directly. Instead, you declare your specific `compilerOptions` in your `tsconfig.json`, and they are merged with or override the base settings provided by this preset. Understand the merging behavior of `extends`.","wrong":"import { CompilerOptions } from 'ts-config-single-spa';","symbol":"CompilerOptions","correct":"// Your tsconfig.json merges with or overrides options defined by ts-config-single-spa\n// Example: { \"compilerOptions\": { \"jsx\": \"react-jsx\" } }"},{"note":"This configuration helps set up the environment, but specific global types for `single-spa` (like `window.singleSpa`) are typically provided by `@types/single-spa` or declared in your project's global declaration files (e.g., `src/global.d.ts`). Developers should not expect `ts-config-single-spa` to export runtime types.","wrong":"import { SingleSpaGlobal } from 'ts-config-single-spa';","symbol":"GlobalTypes","correct":"/// <reference types=\"single-spa\" />\n// or install @types/single-spa"}],"quickstart":{"code":"{\n  \"extends\": \"ts-config-single-spa\",\n  \"compilerOptions\": {\n    \"jsx\": \"react-jsx\", // Adjust based on your framework (e.g., \"preserve\", \"react\", \"vue-jsx\")\n    \"lib\": [\"dom\", \"es2020\"],\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"*\": [\"src/*\"]\n    },\n    \"declaration\": true, // Often desired for microfrontends exporting modules\n    \"outDir\": \"dist\"\n  },\n  \"include\": [\"src/**/*.ts\", \"src/**/*.tsx\"],\n  \"exclude\": [\"node_modules\", \"dist\"]\n}","lang":"json","description":"Demonstrates a basic `tsconfig.json` file extending `ts-config-single-spa` for a microfrontend, including common compiler options and file inclusions."},"warnings":[{"fix":"Review the TypeScript release notes for your target version. Explicitly set `compilerOptions` like `strict: true`, `moduleResolution: \"node\"`, `target: \"es2020\"`, and `rootDir: \".\"` in your `tsconfig.json` if they differ from the new defaults or your project's expected behavior. Always run `tsc --init` in a temporary directory to see the latest default `tsconfig.json`.","message":"Upgrades to newer TypeScript versions (e.g., TypeScript 6.0+) can introduce breaking changes in default compiler options (`strict`, `module`, `target`, `moduleResolution`, `rootDir`). `ts-config-single-spa` will eventually adopt these, which may require explicit configuration in your local `tsconfig.json` to maintain previous behavior if not using strict defaults.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure `compilerOptions.moduleResolution` is set appropriately (e.g., `\"node\"` or `\"bundler\"`). Verify `baseUrl` and `paths` in your `tsconfig.json` are correctly configured to resolve internal package imports. If using a monorepo, explicitly check `webpack-config-single-spa-ts` configurations and ensure `fork-ts-checker-webpack-plugin` is set up correctly for your workspace to prevent stale type errors.","message":"Incorrect module resolution (`moduleResolution`) or `paths` configuration can lead to 'Cannot find module' errors, especially in monorepos or when importing shared utility modules across single-spa applications. This is a common issue when `webpack-config-single-spa-ts` is misconfigured.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Configure `webpack.config.js` to correctly define `externals` for shared libraries. Utilize import maps for in-browser module resolution, and configure your build tool (Webpack, Rollup) to treat these as external. Tools like `systemjs-webpack-interop` or `import-map-externals-webpack-plugin` can assist with this.","message":"When using `webpack-config-single-spa-ts` or similar configurations, ensure that your `webpack.config.js` correctly handles `externals` for shared dependencies (like React, Vue, single-spa itself) to prevent them from being bundled into each microfrontend. This config package doesn't directly manage `webpack` externals, but relies on the overall build setup.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Migrate your `target` to `\"es2015\"` or newer (e.g., `\"es2020\"` or `\"esnext\"`) and update `module` and `moduleResolution` to `\"esnext\"` or `\"bundler\"` if compatible with your runtime and build chain. Be aware of `package.json` `\"type\": \"module\"` implications and ensure your bundles are compatible with in-browser ES modules.","message":"TypeScript 6.0 deprecates `target: \"es5\"` and `moduleResolution: \"node\"` (which refers to Node 10-style resolution). While `ts-config-single-spa` may support older targets, modern `single-spa` setups increasingly leverage newer ECMAScript features and module systems like ESM and import maps.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Ensure your `compilerOptions.lib` array explicitly includes `\"dom\"`, `\"dom.iterable\"`, and `\"es20xx\"` (where `xx` is your target ECMAScript version) as needed. `ts-config-single-spa` aims to provide reasonable defaults, but local overrides might be necessary for specific browser APIs. The current version should include `dom` and `es2020` by default.","message":"TypeScript's default `lib` option might not include `dom.iterable` or `dom.asynciterable` in older configurations, leading to type errors for modern browser APIs. TypeScript 6.0 introduces `dom.iterable` and `dom.asynciterable` into the default `dom` lib.","severity":"gotcha","affected_versions":"<3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the official type declarations: `npm install --save-dev @types/single-spa`. Ensure `compilerOptions.moduleResolution` is set to `\"node\"` (or `\"bundler\"` for newer TS versions) in your `tsconfig.json`. If using `type: \"module\"` in `package.json`, check for `package.json` `\"exports\"` configuration issues for `single-spa` itself.","cause":"TypeScript cannot locate the type definitions for the `single-spa` package, often due to incorrect `moduleResolution` or missing `@types/single-spa`.","error":"TS2307: Cannot find module 'single-spa' or its corresponding type declarations."},{"fix":"Verify the `extends` path: ensure `\"ts-config-single-spa\"` is correctly specified. Check `include` and `exclude` arrays for typos or incorrect glob patterns. Ensure the `ts-config-single-spa` package is correctly installed in `node_modules`.","cause":"Your `tsconfig.json`'s `include` or `exclude` paths are incorrect, or the `extends` path for `ts-config-single-spa` is wrong.","error":"Error: TS6053: File '...' not found. OR TS1005: ',' expected."},{"fix":"Ensure `@types/single-spa` is installed. If manually declaring types, create a `global.d.ts` file with `declare global { interface Window { singleSpa: any; // Or a more specific SingleSpaGlobal type } }` to extend the global `Window` interface.","cause":"The global `window.singleSpa` object's type is not recognized by TypeScript, often because `single-spa` types are not properly loaded.","error":"Property 'singleSpa' does not exist on type 'Window'."}],"ecosystem":"npm"}