Skip to content

New API + CLI, and significant refactor to improve reliability

Pre-release
Pre-release
Compare
Choose a tag to compare
@bradmering bradmering released this 29 Jun 13:23
· 452 commits to main since this release
v0.6.0
1e40f28

0.6.0 introduces two major new tools that will make it much easier to integrate Handoff with existing projects and data pipelines. This release also reorganizes the Handoff code to make the pipeline significantly more robust, easier to extend, and easier to use in existing projects. Our goal with this release is to establish a stable Typescript API as we approach a 1.0 release.

Features

Handoff CLI

Handoff now comes with a CLI toolchain that allows you to run Handoff commands in any context. This CLI replaces the installer from previous versions to scaffold up projects in a directory.

  • Can be installed globally as a node binary npm i -g handoff-app
  • Run in any directory using handoff-app <command>
  • Will detect in the current working root and use that config if present
  • Has sane default configs that will work for normal projects
  • All configurations are sparse, so you can override a single config file and the rest of the config will inherit the defaults
  • Allows users to make config or eject the default config into the current working root
  • Can be run interactively to configure a project or non-interactively with env variables
  • Run handoff-app --help for a full list of commands
  • See https://github.com/Convertiv/handoff-app/blob/main/docs/cli.md for documentation

Handoff Typescript API

Handoff now exposes a full typescript API published as commonjs modules. This API will allow you to use Handoff in your Node 16+ javascript or typescript projects. With just a few lines of code you can have Handoff run programmatically.

This API supersedes and replaces the plugin architecture introduced in 0.5.0. The API call structure is maintained, but now the API can be used directly in existing Node applications and can be used with typescript.

Here's a simple example that will fetch the data down. This example expects a DEV_ACCESS_TOKEN and a FIGMA_PROJECT_ID env variable, or those to be provided in process.env. If not supplied, they will be prompted for when the pipeline is run.

import Handoff from 'handoff-app';
const handoff = new Handoff({
  title: 'Handoff Bootstrap',
  integration: {
    name: 'bootstrap',
    version: '5.3',
  },
});
await handoff.fetch();
  • Fully typed API + full access to all the pipeline functions for transforming the tokens
  • Methods to support fetching tokens, building the documentation app, building the integration, and running the app locally for testing
  • A hook system allowing javascript functions to be passed as callbacks to be executed at points in the pipeline
// This hook will execute after the integration step and allow you to extract
// data from the pipeline and write it to a file
handoff.postIntegration((documentationObject: DocumentationObject, data: HookReturn[]) => {
  const colors = documentationObject.design.color.map((color) => {
    return {
      name: color.name,
      value: color.value,
    };
  });
  data.push({
    filename: 'colors.json',
    data: JSON.stringify(colors, null, 2),
  });
  return data;
});

Improvements

  • The handoff code base was refactored to eliminate the monorepo architecture and consolidate on a more coherent package architecture. This refactoring eliminated a number of weak points and improves reliability.
    • Sharing code between the data pipeline and the Nextjs documentation app is safer
    • The hook architecture introduced in 0.5 was fragile and less secure than we wanted. This reorganization makes a much more robust API, with full access to the typings
    • The previous structure merged configurations in a way that could fail easily. The new architecture reads and merges the various Handoff configurations in a much more robust manor.
    • Previously handoff required a folder architecture, with the proper files, and could fail if those files were moved. Now Handoff can be run in an empty directory, and can accommodate configs being added and removed during operation.
  • Upgrade Nextjs from 12 to 13 providing cleaner, faster application builds
  • Tailwind integration hook has been added to the pipeline

Bugfixes

  • Fixes several style issues in the Bootstrap 5.3 release
  • Corrects a missing caret in Bootstrap 5.2 and 5.3 selects

Changes from last Canary

  • Fixing version df788f9
  • Bumping cli version 70d0ca7
  • 0.6.0 48d1534
  • Merge pull request #54 from Convertiv/release/0.6.0 a4a18c9
  • Tweaks to Changlog 5e16d2a
  • Updating changelog for 277 missing select caret 5f8e180
  • Merge branch 'CONVHAND-277-bootstrap-select-element-integration' into release/0.6.0 17afdc4
  • Writing changelog for 0.6 5a8806d
  • Cleaning up some text d2f025f
  • Remove the unneded closing quote c6202d0
  • Fixing small bugs in pipeline zip output for web app fdf2db3
  • CONVHAND-277 - mapped and extended select form element for Bootstrap 5.2 and 5.3. b14eeef

v0.6.0-8...v0.6.0

Assets 2
Loading