Razzle TypeScript Plugin

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Your `razzle.config.js` is using ES module `import` syntax (e.g., `import { name } from 'module';`) but your `package.json` does not have `"type": "module"` set, or it's being treated as CommonJS.
  fix In your `package.json`, add `"type": "module"` at the top level to enable ESM. Alternatively, rewrite your `razzle.config.js` to use CommonJS `require()` and `module.exports` syntax.

• Error: Can't resolve 'typescript' in '...' or similar webpack build failures related to TypeScript files.

  cause The `typescript` package or its associated Webpack loaders (`ts-loader`) are not installed as dependencies, or your `tsconfig.json` is misconfigured.
  fix Ensure `typescript`, `ts-loader`, and `fork-ts-checker-webpack-plugin` are installed as dev dependencies (`yarn add -D typescript ts-loader fork-ts-checker-webpack-plugin`). Verify that a valid `tsconfig.json` exists in your project root and is correctly configured for your project structure.

• TSXXXX: (some TypeScript compilation error)

  cause These are standard TypeScript compilation errors. While the plugin enables TS, it doesn't solve code-specific issues. Errors can stem from type mismatches, missing definitions, incorrect `tsconfig.json` settings (e.g., `strict` mode, `jsx` option), or incompatible dependencies.
  fix Address the specific TypeScript error message by correcting your code, adjusting your `tsconfig.json` compiler options (e.g., `skipLibCheck`, `noImplicitAny`, `jsx`), or installing `@types/` packages for untyped dependencies. Check `forkTsChecker` options for specific linting rules if applicable.

Warnings

• gotcha Razzle now includes built-in TypeScript support leveraging Babel. This plugin is generally not recommended for new projects unless specific advanced configurations, such as applying Babel transforms to TypeScript files, are required. Using Razzle's native support is often simpler and preferred.
  Fix: Consider removing `razzle-plugin-typescript` and configuring TypeScript directly via Razzle's core features or Babel settings, as demonstrated in Razzle's `with-typescript` example.
• breaking Starting with Razzle 4.2.18, `razzle.config.js` now supports `type:module` in your `package.json` for ESM syntax. Older configurations might encounter `SyntaxError` if they mix CommonJS exports with ESM `import` statements without properly declaring `"type": "module"` in `package.json` or vice-versa.
  Fix: Ensure your `razzle.config.js` matches your project's module system. If using ESM `import/export` in `razzle.config.js`, add `"type": "module"` to your `package.json`. Otherwise, stick to CommonJS `require/module.exports` syntax.
• gotcha This plugin relies on `ts-loader` and `fork-ts-checker-webpack-plugin`. These packages, along with `typescript` itself, are peer dependencies or expected dependencies and must be installed separately in your project.
  Fix: Install required packages: `yarn add -D typescript ts-loader fork-ts-checker-webpack-plugin` or `npm install --save-dev typescript ts-loader fork-ts-checker-webpack-plugin`. Also ensure a `tsconfig.json` file is present in your project root.

Install

• npm install razzle-plugin-typescript npm
• yarn add razzle-plugin-typescript yarn
• pnpm add razzle-plugin-typescript pnpm

Imports

• typescript plugin (default)
  wrong:

  import { typescript } from 'razzle-plugin-typescript'

  correct:

  module.exports = {
    plugins: ['typescript'],
  };

  Razzle plugins are typically configured in `razzle.config.js` by referencing their name as a string in the `plugins` array. This is not a standard ES module import.
• typescript plugin (with options)
  wrong:

  const config = require('razzle-plugin-typescript');
  // ... then try to manipulate config.plugins

  correct:

  module.exports = {
    plugins: [
      {
        name: 'typescript',
        options: {
          useBabel: true, // Example: Enable Babel processing for TS files
          tsLoader: { transpileOnly: false }
        },
      },
    ],
  };

  For custom configurations, the plugin is specified as an object with a `name` and `options` property within the `plugins` array.
• TypeScript types (example)

  import type { WebpackOptions } from 'webpack';

  While `razzle-plugin-typescript` enables TypeScript, type imports for core Razzle configurations or Webpack itself would come from their respective packages or `@types/` definitions.

Quickstart

This configuration enables the TypeScript plugin in Razzle with custom `ts-loader` and `fork-ts-checker-webpack-plugin` options, and adds TypeScript extensions to Webpack's resolution paths.

/* razzle.config.js */
const RazzlePluginTypescript = require('razzle-plugin-typescript'); // Not strictly imported, but for context of plugin availability

module.exports = {
  plugins: [
    {
      name: 'typescript',
      options: {
        // Set useBabel to true if you want to keep using babel for JS/TS interoperability,
        // or if you want to apply any babel transforms to typescript files.
        useBabel: false,
        // Override ts-loader options
        tsLoader: {
          transpileOnly: true,
          experimentalWatchApi: true,
        },
        // Override fork-ts-checker-webpack-plugin options for type checking
        forkTsChecker: {
          eslint: {
            files: ['*.js', '*.jsx', '*.ts', '*.tsx'],
          },
          async: process.env.NODE_ENV === 'development',
          formatter: 'codeframe',
        },
      },
    },
  ],
  // Optional: Add '.ts' and '.tsx' to Razzle's default extensions
  modifyWebpackConfig(config, { target, dev }, webpack) {
    config.resolve.extensions = [...config.resolve.extensions, '.ts', '.tsx'];
    return config;
  }
};

// Ensure required peer dependencies are installed: 
// yarn add -D typescript ts-loader fork-ts-checker-webpack-plugin
// Also, ensure a tsconfig.json exists in your project root.