@sapphire/docusaurus-plugin-ts2esm2cjs v2.0.2

@sapphire/docusaurus-plugin-ts2esm2cjs

Docusaurus Remark plugin for converting TypeScript code to ESM and CJS code.

Description

This is a plugin for Docusaurus that adds support for a ts2esmcjs meta tag for code blocks. It will transpile your TypeScript code into ESM and CJS code, and format it properly. It will then give you a component using Tabs where users can select their preferred language. By default this will sync across all code blocks that use this meta tag, you can disable that through the plugin options.

Usage

In your docusaurus.config.js, for the plugins where you need this feature (doc, blog, pages, etc.), register it in the remarkPlugins option. (See Docs configuration for more details on configuration format)

// docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          remarkPlugins: [[require('@sapphire/docusaurus-plugin-ts2esm2cjs')]]
        },
        pages: {
          remarkPlugins: [require('@sapphire/docusaurus-plugin-ts2esm2cjs')]
        },
        blog: {
          // ...
        }
      }
    ]
  ]
};

And then use it by adding the ts2esm2cjs key to the code block:

meta: _typescript ts2esm2cjs_

import { Command, Args } from '@sapphire/framework';
import type { Message } from 'discord.js';

export class EchoCommand extends Command {
  public constructor(context: Command.Context, options: Command.Options) {
    super(context, {
      ...options,
      aliases: ['parrot', 'copy'],
      description: 'Replies with the text you provide'
    });
  }

  public async messageRun(message: Message, args: Args) {
    // ...
  }
}

Line Highlighting

As you may be aware, Docusaurus supports Line Highlighting for code blocks. As line highlighting relies on meta just like this plugin would, we would normally run into a bit of a conflict as to what to set in the meta tag. On top of that, often you'll want to highlight different lines for JavaScript as opposed to TypeScript. To solve these issues this plugin supports a unique syntax of setting the meta tag. You can configure the line highlighting by adding a | character after the plugin meta tag. This can be done twice, wherein the first line highlight configuration will be for the JavaScript and ESM code blocks, whereas the second will be for the TypeScript code block.

For example consider the following code block:

meta: _typescript ts2esm2cjs|{1,4-10}|{1,5-11}_

import { Command, Args } from '@sapphire/framework';
import type { Message } from 'discord.js';

export class EchoCommand extends Command {
  public constructor(context: Command.Context, options: Command.Options) {
    super(context, {
      ...options,
      aliases: ['parrot', 'copy'],
      description: 'Replies with the text you provide'
    });
  }

  public async messageRun(message: Message, args: Args) {
    // ...
  }
}

This will give you a three code blocks in a Tabs layout with the JavaScript and ESM code blocks having lines 1 and 4 through 10 highlighted, and the TypeScript code block having lines 1 and 5 through 11 highlighted.

Code formatting

The output JS and ESM code is formatted using Prettier. The default configuration is:

{
  "endOfLine": "lf",
  "printWidth": 120,
  "quoteProps": "as-needed",
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "none",
  "useTabs": false,
  "parser": "babel"
}

You can customize this by passing prettierConfig to the plugin options.

TypeScript compiler options

The ESM code is transpiled from TypeScript using the TypeScript compiler with the following base configuration:

{
  "newLine": "lf",
  "removeComments": false,
  "esModuleInterop": true,
  "pretty": true,
  "module": "ESNext",
  "moduleResolution": "Node",
  "target": "ESNext"
}

You can customize this by passing typescriptCompilerOptions to the plugin options. However, you cannot customize the module, moduleResolution, or target options.

Buy us some doughnuts

Sapphire Community is and always will be open source, even if we don't get donations. That being said, we know there are amazing people who may still want to donate just to show their appreciation. Thank you very much in advance!

We accept donations through Open Collective, Ko-fi, Paypal, Patreon and GitHub Sponsorships. You can use the buttons below to donate through your method of choice.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!