React Static TypeScript Plugin

Common errors

• Module not found: Error: Can't resolve 'typescript' in '...'

  cause The `typescript` peer dependency is not installed in the project.
  fix Run `npm install typescript --save-dev` to install the TypeScript compiler.

• ERROR in TS[...] Property '...' does not exist on type '...'.

  cause A TypeScript type error was detected during compilation when `typeCheck` is enabled. This prevents the build from completing.
  fix Correct the TypeScript type errors in your source code. If the error is intentional or a temporary workaround, consider casting or modifying the type definitions. For faster local iteration, you may set `typeCheck: false` in the plugin options (not recommended for production builds).

• Error: No default export for template [...]

  cause A React Static template (e.g., a page component or `src/App.tsx`) is missing a default export, which is required by the framework.
  fix Ensure all React Static page components and `src/App.tsx` have a `export default MyComponent;` statement.

• Failed to load tsconfig.json: [...]

  cause The `tsconfig.json` file is either missing from the project root or contains invalid JSON syntax, preventing the TypeScript compiler from configuring correctly.
  fix Verify that `tsconfig.json` exists in your project's root directory and that its content is valid JSON. Use a JSON linter or editor to check for syntax errors.

Warnings

• breaking Node.js v10 support was removed across the React Static v7.2.0 ecosystem, including this plugin. Projects now require Node.js v12 or higher for compatibility.
  Fix: Upgrade your Node.js environment to version 12 or newer to ensure the build process functions correctly.
• breaking The `v7.6.0` release of React Static brought an update to its `emotion` plugin to support Emotion v11. If your project uses Emotion, this might introduce breaking changes requiring updates to your Emotion configuration and component styling.
  Fix: Refer to Emotion's v11 upgrade guide and adjust your Emotion setup and component code accordingly for compatibility.
• gotcha Disabling type checking via the `typeCheck: false` option can lead to uncaught TypeScript errors during compilation, potentially resulting in runtime issues that would otherwise be caught at build time.
  Fix: For robust development, it is highly recommended to keep `typeCheck: true` and resolve all TypeScript errors. Only disable it for specific performance needs, ensuring type safety is managed by other tools (e.g., editor, CI linting).
• gotcha Missing or incorrectly configured `tsconfig.json` will prevent the plugin from properly compiling TypeScript files, leading to build failures or unexpected behavior. Ensure it aligns with React and modern JavaScript practices.
  Fix: Ensure a valid `tsconfig.json` is present at the project root, typically including `jsx: "preserve"`, `lib: ["es2015", "dom"]`, and `moduleResolution: "node"`.
• gotcha The `typescript` peer dependency must be installed in your project, along with `@types/react` as a dev dependency. Failure to do so will result in compilation errors or missing type definitions.
  Fix: Run `npm install typescript @types/react --save-dev` to ensure all necessary type tools are available for your project.

Install

• npm install react-static-plugin-typescript npm
• yarn add react-static-plugin-typescript yarn
• pnpm add react-static-plugin-typescript pnpm

Imports

• PluginConfiguration
  wrong:

  import { ReactStaticTypeScriptPlugin } from 'react-static-plugin-typescript';

  correct:

  export default {
    plugins: ['react-static-plugin-typescript'],
  }

  This plugin is configured by its string name within the `plugins` array in `static.config.js`; it does not export runtime symbols for direct import into user application code. `static.config.js` itself typically uses ESM `export default`.
• PluginWithOptions
  wrong:

  const pluginConfig = require('react-static-plugin-typescript'); // Incorrect for static.config.js and for passing options

  correct:

  export default {
    plugins: [['react-static-plugin-typescript', { typeCheck: true }]],
  }

  To pass options to the plugin, wrap the plugin's string name and an options object in an array within the `plugins` array. This is the standard way for React Static plugins.

Quickstart

This quickstart demonstrates how to install the plugin, add it to your `static.config.js` with options for type checking, and configure a basic `tsconfig.json` for a new or existing React Static project using TypeScript.

npm install react-static-plugin-typescript @types/react --save-dev

// static.config.js (in your project root)
export default {
  plugins: [
    // Add the TypeScript plugin, optionally with typeCheck enabled
    ['react-static-plugin-typescript', { typeCheck: true }]
  ],
  // Other React Static configurations...
}

// tsconfig.json (in your project root)
{
  "compilerOptions": {
    "target": "es2015",
    "module": "esnext",
    "lib": ["es2015", "dom"],
    "moduleResolution": "node",
    "skipLibCheck": true,
    "isolatedModules": true,
    "noEmit": true,
    "allowJs": true,
    "jsx": "preserve",
    "sourceMap": true,
    "removeComments": false,
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "build"]
}