@braid-design-system/source.macro

A Babel macro for authoring code snippets as code.

Example and use cases

In Braid, documentation is authored as code. Rather than writing snippets and code examples as strings, the source macro enables them to be written as code instead. The first argument passed to the macro will be returned both as a string and as the original value inside an object:

1import source from '@braid-design-system/source.macro';
2
3const result = source(<div>Hello world</div>);
4// Returns { code: '<div>Hello world</div>', value: <div>Hello world</div> }

This macro enables several capabilities that are not easily achievable with snippets:

• Snippets can be type-checked and linted
• Snippets can be rendered directly in documentation
• The code string representing the snippet can still be displayed in documentation, copied to the clipboard, or in the case of Braid, used to generate a Playroom link

Setup

Install @braid-design-system/source.macro:

1npm install --save-dev @braid-design-system/source.macro

Install and configure babel-plugin-macros:

1npm install --save-dev babel-plugin-macros

1// babel.config.js
2module.exports = {
3  plugins: ['babel-plugin-macros'],
4};

Configuration

The source macro supports the following configuration options:

1// babel.config.js
2module.exports = {
3  plugins: [
4    [
5      'babel-plugin-macros',
6      {
7        source: {
8          // Whether to return a code string and the original value in an object, or just the code string. Defaults to `false`.
9          codeOnly: true,
10          // Whether to format the code string using Prettier. Defaults to `true`.
11          formatWithPretteir: false,
12        },
13      },
14    ],
15  ],
16};

Alternatives

react-element-to-jsx-string is a library that converts JSX elements to strings, but it cannot serialize functions, and the formatting of the resulting string is subpar relative to Prettier.