Support TypeScript in Docusaurus config

[MarkShawn2020]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

Here I would offer a minimal example on how to create a config file based on typescript and make it run.

Has this been requested on Canny?

No response

Motivation

In TypeScript Support | Docusaurus, it writes that It is not possible to use a TypeScript config file in Docusaurus unless you compile it yourself to JavaScript.

Although JSDoc can be helpful of preventing you make some mistakes about field types, it's not acting well in every places.

Take my own example, I designed an data structure for frontend, and I also need to generate the data from the backend (i.e. customFileds in docusaurus.config.js), then I would suffer with types declaration:

And a typescript config is necessary to me.

API design

Source Code

// config/src/index.ts

import type {Config} from '@docusaurus/types'

// here is a sample of async config, and it would be also OK to just put a Config here
export const configCreatorAsync = async (): Promise<Config> => ({
  ...
  baseUrl: '/',
  docs: {...},
  blog:{...},
  ...
})

export default configCreatorAsync

// config/tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",

    "module": "commonjs", // docusaturus is based on CJS now
    "target": "esnext",   // to make the transpiled js more readable than es5 or like

    "outDir": "../..",    // directly output all the generated files under current website root dir, so **[important]**
                          // prevent the js failing to run in case of any path problems
    "rootDir": "../..",   // keep the project structure

    "resolveJsonModule": true,   // json support
    "esModuleInterop": true,     // esm support
    "moduleResolution": "node",  // node support

    "skipLibCheck": true,        // ensure true to avoid annoying type inspection errors
    "skipDefaultLibCheck": true, // the same as above 

    "sourceMap": false,          // unnecessary to generate map
    "declaration": false         // unnessary to genrate d.ts            
  },
  "include": [
    "src/**/*.ts",
    ...     // other files we need to be imported by src under src, e.g. my `../src/ds/tasks.ts`
  ],
  "exclude": [
    "**/node_modules"
  ]
}

// package.json
{
  "scripts": {
    "prestart": "cd config && tsc",
    "start": "docusaurus start --config config/src/index.js",
  }
}

Attention

• prevent using path alias in our ts config file, since it would introduce troubles when transpiling into js, tsconfig-paths or tsc-alias may be helpful if you need it.
• It's ok to not use outDir and rootDir in tsconfig.json, but it would fail if using tsc-alias at the same time since a outDir is need.
• It's ok to just write one ts config file just like what the docusaurus.config.js did, but the config would become harder to manage as you have seen.

Other Practices

I also tried to use webpack to pack all the ts files into one docusaurus.config.webpack.js file and almost succeded with these settings:

// webpack.config.ts

import path from "path"

import type {Configuration} from 'webpack/types'

import nodeExternals from 'webpack-node-externals'

const config: Configuration = {
  resolve: {
    extensions: [".tsx", ".ts", ".jsx", ".js"],
    alias: {
      // target for tsconfig.json, ref: https://webpack.js.org/configuration/resolve/#resolvealias
      "@site": path.resolve(__dirname, "../"),
    }
  },
  entry: "./src/index.ts",
  output: {
    filename: 'docusaurus.config.webpack.js',
    path: path.resolve(__dirname, ".."),
    library: { // --> IMPORTANT <--
      type: 'commonjs-module',
      export: 'default'
    }
  },
  target: 'node',             // must enable, otherwise can't resolve `fs|path`
  node: {
    __dirname: true          // /my-website/src/css/theme.css
    // __dirname: false      // /my-website/css/theme.css (default)
  },
  externals: [nodeExternals()],

  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      }
    ],
  },
};


const isProduction = process.env.NODE_ENV === "production";

module.exports = () => {
  if (isProduction) {
    config.mode = "production";
  } else {
    config.mode = "development";
  }
  return config;
};

But it failed with the unknown error request argument is not a string, which seems raised by the webpack inner docusaurus.

Have you tried building it?

No response

Self-service

• [X] I'd be willing to contribute this feature to Docusaurus myself.

[Josh-Cena]

Definitely on our roadmap. You can use ts-node to load a TS config: https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/website/docusaurus.config.js

[MarkShawn2020]

Definitely on our roadmap. You can use ts-node to load a TS config: https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/website/docusaurus.config.js

GREAT JOB！

[Josh-Cena]

We'll keep it open. It's on our todo list.

[MarkShawn2020]

I just tried the script based on ts-node, it runs quite well !

But it would fail when using alias, e.g. @site, in our backend.

Since the ts-node has been used, it's natural now to combiine it with tsconfig-paths.

I modified like this:

'use strict';

// source:  https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/website/docusaurus.config.js
// ref of tsconfig-paths: https://github.com/dividab/tsconfig-paths#bootstrapping-with-explicit-params

+ require("tsconfig-paths").register({
+    baseUrl: "./",
+    paths: require("./tsconfig.json").compilerOptions.paths,
+ });

require('ts-node').register({
    scope: true,
    scopeDir: __dirname,
    swc: true,
    transpileOnly: true,
});

module.exports = require('./config/src/index.ts');

And a manual alias is in need since extend would let my IDE unhappy:

{
  "compilerOptions": {
    "resolveJsonModule": true, // can be omitted, maybe has been handled by ts-node 
    "esModuleInterop": true,   // cannot be omitted
    "paths": {                 // handle the path aliases
      "@site/*": ["./*"]
    }
  }
}

Thanks for all of your great work, you did save me a lot of time and enlighten me as well ~

[slorber]

For reference Gatsby recently added support for TS config files. That's worth studying their solution for the final implementation: https://github.com/gatsbyjs/gatsby/discussions/34613

I also found this interesting: https://github.com/egoist/bundle-require

[rxliuli]

I just tried the script based on ts-node, it runs quite well !

But it would fail when using alias, e.g. @site, in our backend.

Since the ts-node has been used, it's natural now to combiine it with tsconfig-paths.

I modified like this:

'use strict';

// source:  https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/website/docusaurus.config.js
// ref of tsconfig-paths: https://github.com/dividab/tsconfig-paths#bootstrapping-with-explicit-params

+ require("tsconfig-paths").register({
+    baseUrl: "./",
+    paths: require("./tsconfig.json").compilerOptions.paths,
+ });

require('ts-node').register({
    scope: true,
    scopeDir: __dirname,
    swc: true,
    transpileOnly: true,
});

module.exports = require('./config/src/index.ts');

And a manual alias is in need since extend would let my IDE unhappy:

{
  "compilerOptions": {
    "resolveJsonModule": true, // can be omitted, maybe has been handled by ts-node 
    "esModuleInterop": true,   // cannot be omitted
    "paths": {                 // handle the path aliases
      "@site/*": ["./*"]
    }
  }
}

Thanks for all of your great work, you did save me a lot of time and enlighten me as well ~

This doesn't really solve the problem, e.g. when importing a module from an external esm it will fail

Error [ERR_REQUIRE_ESM]: require() of ES Module node_modules\unist-util-visit\index.js from docusaurusConfig.ts not supported.

[Josh-Cena]

@rxliuli Node ESM is orthogonal to TS. Even if you write TS in an ESM-like syntax, you are still downleveling it to CJS at runtime. Native support for ESM is tracked in https://github.com/facebook/docusaurus/issues/6520.