{"id":11628,"library":"razzle-plugin-typescript","title":"Razzle TypeScript Plugin","description":"razzle-plugin-typescript integrates TypeScript support into Razzle applications, allowing developers to use TypeScript for both client-side and server-side code. It provides granular configuration options for underlying tools like `ts-loader` and `fork-ts-checker-webpack-plugin`, enabling custom setups for compilation and type checking. The package is currently at version 4.2.18, receiving updates in sync with the core Razzle framework. A key consideration is that Razzle now includes built-in TypeScript support via Babel. As such, this plugin is primarily recommended for projects requiring advanced or specific TypeScript configurations, such as applying certain Babel transforms to `.ts` files, rather than for basic TypeScript integration, where the native Razzle support is generally sufficient and simpler.","status":"maintenance","version":"4.2.18","language":"javascript","source_language":"en","source_url":"https://github.com/jaredpalmer/razzle","tags":["javascript"],"install":[{"cmd":"npm install razzle-plugin-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add razzle-plugin-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add razzle-plugin-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Razzle framework, required for plugin functionality.","package":"razzle","optional":false},{"reason":"Provides utility functions used by Razzle plugins.","package":"razzle-dev-utils","optional":false},{"reason":"The plugin configures Webpack loaders and plugins for TypeScript processing.","package":"webpack","optional":false},{"reason":"Webpack loader for TypeScript files, configurable via plugin options.","package":"ts-loader","optional":true},{"reason":"Webpack plugin for asynchronous TypeScript type checking, configurable via plugin options.","package":"fork-ts-checker-webpack-plugin","optional":true}],"imports":[{"note":"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.","wrong":"import { typescript } from 'razzle-plugin-typescript'","symbol":"typescript plugin (default)","correct":"module.exports = {\n  plugins: ['typescript'],\n};"},{"note":"For custom configurations, the plugin is specified as an object with a `name` and `options` property within the `plugins` array.","wrong":"const config = require('razzle-plugin-typescript');\n// ... then try to manipulate config.plugins","symbol":"typescript plugin (with options)","correct":"module.exports = {\n  plugins: [\n    {\n      name: 'typescript',\n      options: {\n        useBabel: true, // Example: Enable Babel processing for TS files\n        tsLoader: { transpileOnly: false }\n      },\n    },\n  ],\n};"},{"note":"While `razzle-plugin-typescript` enables TypeScript, type imports for core Razzle configurations or Webpack itself would come from their respective packages or `@types/` definitions.","symbol":"TypeScript types (example)","correct":"import type { WebpackOptions } from 'webpack';"}],"quickstart":{"code":"/* razzle.config.js */\nconst RazzlePluginTypescript = require('razzle-plugin-typescript'); // Not strictly imported, but for context of plugin availability\n\nmodule.exports = {\n  plugins: [\n    {\n      name: 'typescript',\n      options: {\n        // Set useBabel to true if you want to keep using babel for JS/TS interoperability,\n        // or if you want to apply any babel transforms to typescript files.\n        useBabel: false,\n        // Override ts-loader options\n        tsLoader: {\n          transpileOnly: true,\n          experimentalWatchApi: true,\n        },\n        // Override fork-ts-checker-webpack-plugin options for type checking\n        forkTsChecker: {\n          eslint: {\n            files: ['*.js', '*.jsx', '*.ts', '*.tsx'],\n          },\n          async: process.env.NODE_ENV === 'development',\n          formatter: 'codeframe',\n        },\n      },\n    },\n  ],\n  // Optional: Add '.ts' and '.tsx' to Razzle's default extensions\n  modifyWebpackConfig(config, { target, dev }, webpack) {\n    config.resolve.extensions = [...config.resolve.extensions, '.ts', '.tsx'];\n    return config;\n  }\n};\n\n// Ensure required peer dependencies are installed: \n// yarn add -D typescript ts-loader fork-ts-checker-webpack-plugin\n// Also, ensure a tsconfig.json exists in your project root.","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.2.18"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","cause":"The `typescript` package or its associated Webpack loaders (`ts-loader`) are not installed as dependencies, or your `tsconfig.json` is misconfigured.","error":"Error: Can't resolve 'typescript' in '...' or similar webpack build failures related to TypeScript files."},{"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.","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.","error":"TSXXXX: (some TypeScript compilation error)"}],"ecosystem":"npm"}