Example Project

Here's a demo project you can check out to get started fast https://github.com/Convertiv/handoff-0-6-0/

Get Started

1. Run npm install --save handoff-app
2. Add handoff to your code. Create handoff.ts

1import Handoff from "handoff-app";
2
3const handoff = new Handoff({
4  // You can customize the configuration here
5});
6handoff.fetch();
7

3. Build your typescript tsc
4. Run your project node handoff.js

Methods

Methods of the handoff class can be called to run actions in the

init

1handoff.init();
2

Init will check and build the local state, including the configuration. You probably don't need to call this method since it is executed as part of the class constructor

fetch

1handoff.fetch();
2

Fetch will connect to the defined Figma file id provided in the env. If no env or file is found, it will interactively request one. Then it will export all of the tokens and generated data into an exported directory in the local working root.

build

1handoff.build();
2

Build will take the exported artifacts and build a react documentation site from those artifacts. The build html site will be exported to the out directory in the current working root

This method will throw an error if the exported directory or the tokens.json files do not exist

integration

1handoff.integration();
2

The integration method will run just the preview and integration generation. This step is done as part of the build step, but its often useful to be able to generate only the integration code.

Hooks

Hooks allow a typescript or javascript app to interact with the pipeline. This is especially useful for modifying or extending the output of the pipeline. To use a hook in your project, once you've instantiated the handoff object, you can call one of the hook methods and pass a function to the method. The hook function will be called at the appropriate point in the pipeline.

For example if you want to alter the integration output, you can do this -

1import Handoff from "handoff-app";
2
3const handoff = new Handoff({
4  // You can customize the configuration here
5});
6
7handoff.postIntegration(
8  (documentationObject: DocumentationObject, data: HookReturn[]) => {
9    const colors = documentationObject.design.color.map((color) => {
10      return {
11        name: color.name,
12        value: color.value,
13      };
14    });
15    data.push({
16      filename: "colors.json",
17      data: JSON.stringify(colors, null, 2),
18    });
19    return data;
20  }
21);
22
23handoff.fetch();
24

postIntegration

The Post integration hook will allow you to add a function that will be executed after the integration build is complete. The function accepts two arguments -

arguments

• tokens: DocumentationObject This is an instance of the exported DocumentationObject containing all of the tokens.
• data: HookReturn[] This an array of HookReturns, consisting of filename and data. Each object in this array will be written out to exported/{integration}-tokens

return The hook must return an array of HookReturn objects, or an empty array

Example

1handoff.postIntegration(
2  (documentationObject: DocumentationObject, data: HookReturn[]) => {
3    const colors = documentationObject.design.color.map((color) => {
4      return {
5        name: color.name,
6        value: color.value,
7      };
8    });
9    data.push({
10      filename: "colors.json",
11      data: JSON.stringify(colors, null, 2),
12    });
13    return data;
14  }
15);
16

postBuild

This function is called after the app build is complete.

arguments

• tokens: DocumentationObject This is an instance of the exported DocumentationObject containing all of the tokens.

returns Nothing is returned from the postBuild hook

postCssTransformer

This function is called after the css generation is complete. It allows an application to alter the css generation in transit

arguments

• tokens: DocumentationObject This is an instance of the exported DocumentationObject containing all of the tokens.
• css: CssTransformerOutput This is an object containing all of the tokens for components and foundations, formatted as CSS variables

returns

• css: CssTransformerOutput This is an object containing all of the tokens for components and foundations, formatted as CSS variables. Any changes you return here will be written to the css files

postCssTransformer

This function is called after the css generation is complete. It allows an application to alter the css generation in transit. It will allow you to alter the transformed output prior to being written to disk.

arguments

• tokens: DocumentationObject This is an instance of the exported DocumentationObject containing all of the tokens.
• css: CssTransformerOutput This is an object containing all of the tokens for components and foundations, formatted as CSS variables

returns

• css: CssTransformerOutput This is an object containing all of the tokens for components and foundations, formatted as CSS variables. Any changes you return here will be written to the css files.

postScssTransformer

This function is called after the scss generation is complete. It allows an application to alter the scss generation in transit. It will allow you to alter the transformed output prior to being written to disk.

arguments

• tokens: DocumentationObject This is an instance of the exported DocumentationObject containing all of the tokens.
• scss: CssTransformerOutput This is an object containing all of the tokens for components and foundations, formatted as SCSS variables

returns

• css: CssTransformerOutput This is an object containing all of the tokens for components and foundations, formatted as SCSS variables. Any changes you return here will be written to the scss files.

postTypeTransformer

Handoff generates a set of scss files that list all the possible types of a component (type, state, activity, size, theme, etc.). This allows frontend engineers to iterate over the types and build scss maps with the variables.

This function is called after the type generation is complete. It allows an application to alter the type generation in transit. It will allow you to alter the transformed output prior to being written to disk.

arguments

• tokens: DocumentationObject This is an instance of the exported DocumentationObject containing all of the tokens.
• scss: CssTransformerOutput This is an object containing all of the type arrays for components and foundations, formatted as SCSS variables

returns

• css: CssTransformerOutput This is an object containing all of the tokens for components and foundations, formatted as type variables. Any changes you return here will be written to the scss type files.

modifyWebpackConfig

When the application is built, Handoff uses webpack to compile css, scss, and javascript in the entry point to build a little live preview of the components. This hook accepts a webpack.Configuration as the first argument and allows you to alter and return that configuration.

arguments

• webpackConfig: webpack.Configuration This is a full webpack configuration.

returns

• webpackConfig: webpack.Configuration Return the webpack configuration that you have altered to fit your needs.

Example

1export const modifyWebpackConfigForTailwind = (
2  webpackConfig: webpack.Configuration
3): webpack.Configuration => {
4  // Enable webpack dev mode
5  webpackConfig.mode = "development";
6  return webpackConfig;
7};
8

configureExportables

This hook allows you to alter the exportable list. You could do this by ejecting the handoff configuration and modifying the list, but this hook allows you to alter the exportable list with just a couple of lines of code rather than exporting the whole list

arguments

• exportables: string[] The current list of exportables

returns

• exportables: string[] Return the list with whatever additions and subtractions you need for your application.