single-spa TypeScript Configuration

3.0.0 · active · verified Sun Apr 19

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.

Common errors

```
TS2307: Cannot find module 'single-spa' or its corresponding type declarations.
```
cause TypeScript cannot locate the type definitions for the `single-spa` package, often due to incorrect `moduleResolution` or missing `@types/single-spa`.

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.
```
Error: TS6053: File '...' not found. OR TS1005: ',' expected.
```
cause Your `tsconfig.json`'s `include` or `exclude` paths are incorrect, or the `extends` path for `ts-config-single-spa` is wrong.

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`.
```
Property 'singleSpa' does not exist on type 'Window'.
```
cause The global `window.singleSpa` object's type is not recognized by TypeScript, often because `single-spa` types are not properly loaded.

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.

Warnings

breaking 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.
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`.
gotcha 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.
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.
gotcha 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.
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.
deprecated 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.
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.
gotcha 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.
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.

Install

npm install ts-config-single-spa npm
yarn add ts-config-single-spa yarn
pnpm add ts-config-single-spa pnpm

Imports

TsConfigExtends
wrong:
```
import 'ts-config-single-spa';
```
correct:
```
{ "extends": "ts-config-single-spa" }
```
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`.
CompilerOptions
wrong:
```
import { CompilerOptions } from 'ts-config-single-spa';
```
correct:
```
// Your tsconfig.json merges with or overrides options defined by ts-config-single-spa
// Example: { "compilerOptions": { "jsx": "react-jsx" } }
```
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`.
GlobalTypes
wrong:
```
import { SingleSpaGlobal } from 'ts-config-single-spa';
```
correct:
```
/// <reference types="single-spa" />
// or install @types/single-spa
```
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.

Quickstart

Demonstrates a basic `tsconfig.json` file extending `ts-config-single-spa` for a microfrontend, including common compiler options and file inclusions.

{
  "extends": "ts-config-single-spa",
  "compilerOptions": {
    "jsx": "react-jsx", // Adjust based on your framework (e.g., "preserve", "react", "vue-jsx")
    "lib": ["dom", "es2020"],
    "baseUrl": ".",
    "paths": {
      "*": ["src/*"]
    },
    "declaration": true, // Often desired for microfrontends exporting modules
    "outDir": "dist"
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist"]
}

view raw JSON →