Des2Code Code Import — How to Use

Summary

Imports Storybook components from a frontend codebase into a Guinness project so they can be used as Des2Code matching targets. The importer sends component source and styles, captures Storybook stories as rendered variations. Index rebuilding is a separate command.

Get the importer

Copy script/des2code-code-import/, including .env.example, into the frontend repository root as des2code-code-import/.

Add these package scripts if the project does not already define them:

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "gen:storybook-screenshots": "node des2code-code-import/generate-screenshots.mjs",
    "guinness:des2code-code-import": "node des2code-code-import/import.mjs"
  }
}

The importer calls npm run build-storybook when storybook-static/index.json is missing, so the build-storybook script name is required. The Storybook development command may differ; set STORYBOOK_SERVER_COMMAND when the default npm run storybook -- --ci does not apply.

Prerequisites

• Node.js 22 or newer and an available npm command
• Project dependencies installed
• Storybook installed and configured in the frontend project
• npm run build-storybook writes the Storybook index to storybook-static/index.json
• At least one Storybook story inside the configured component root
• playwright installed in the project
• Google Chrome installed, or Playwright Chromium installed for bundled-browser mode
• Read access to component source, styles, fonts, and assets used by the stories
• Write access to the configured local output directory
• Network access to the target Guinness backend
• A current Cognito user access token for a user with access to the target organization and project

Install Playwright when it is not already available:

npm install --save-dev playwright

The default screenshot browser is the local Google Chrome channel. If Chrome is unavailable, install Playwright Chromium and use bundled-browser mode:

npx playwright install chromium

PLAYWRIGHT_CHANNEL=bundled

Prepare Storybook for screenshots

Each component state that should become a Guinness variation must be exposed as a Storybook story. The story import path must be inside CODE_IMPORT_COMPONENTS_DIR.

The story file and its implementation must use this local layout:

components/
└── button/
    ├── index.stories.tsx
    ├── index.tsx
    └── index.module.scss

For each story import path, the importer reads sibling implementation files with a .cjs, .js, .jsx, .mjs, .ts, or .tsx extension and sibling .css, .less, .sass, or .scss files. It does not follow imports into other directories. A story stored separately from its component source, or styles available only through a shared global import, will not produce a complete source record.

Stories should render independently and consistently:

• Load required styles, fonts, icons, images, and other assets in Storybook.
• Mock authentication, API data, dates, and other external state when needed.
• Avoid leaving a story in a loading state after its initial render.
• Ensure the Storybook iframe can render the story without manual interaction.
• Ensure browser requests for fonts, images, and other network assets succeed from the Storybook iframe.

The importer builds Storybook when storybook-static/index.json is absent, starts the configured Storybook server when necessary, waits for the story root, waits 500 ms, waits for fonts, disables CSS animations, and captures the rendered component. It does not wait for arbitrary application-specific async work, so data-dependent states must be ready within that window. The normal import uses the desktop viewport at 1280 × 720.

Existing screenshots are reused. Only missing stories are captured unless screenshot regeneration is requested explicitly.

Configure the import

Run the following commands from the frontend repository root.

Create the local environment file:

cp des2code-code-import/.env.example des2code-code-import/.env

Set the target, project paths, and authentication values in des2code-code-import/.env:

Variable	Value
GUINNESS_API_URL	Target Guinness backend stage URL or URL ending in /api/v1
GUINNESS_USER_TOKEN	Current Cognito user access token; do not use an email/password pair
GUINNESS_ORGANIZATION_ID	Target organization ID
GUINNESS_PROJECT_ID	Target project ID
CODE_IMPORT_COMPONENTS_DIR	Root containing the Storybook component sources
CODE_IMPORT_OUTPUT_DIR	Local screenshots, manifests, and reports; defaults to des2code-code-import/output
STORYBOOK_BASE_URL	Storybook server URL; defaults to http://127.0.0.1:6006
STORYBOOK_SERVER_COMMAND	Command used to start Storybook when the server is unavailable
PLAYWRIGHT_CHANNEL	Browser channel; defaults to chrome, or use bundled
GUINNESS_CONNECT_TO	Optional local host:port used while preserving the target URL's TLS hostname

Replace all URL, organization, project, and component-path values from .env.example; do not assume the template targets the intended Guinness project.

Before adding a token, add these paths to the repository root .gitignore:

/des2code-code-import/.env
/des2code-code-import/output/

Use the environment file or --token-file for the access token; do not pass a token directly on the command line because package manager and process output may expose it.

When GUINNESS_CONNECT_TO is used, install its runtime dependency:

npm install --save-dev undici

Validate screenshot capture

Replace <story-filter> with a Storybook title, story ID, name, or import path from the project. The screenshot command treats this regular expression as case-sensitive.

Build the Storybook index and check which stories match without launching a browser:

npm run build-storybook
npm run gen:storybook-screenshots -- \
  --dry-run \
  --include '<story-filter>'

Capture one matching story:

npm run gen:storybook-screenshots -- \
  --include '<story-filter>' \
  --limit 1

Confirm that the screenshot and manifest.json are present under des2code-code-import/output/screenshots/ before testing the Guinness import.

Validate the import

Check one component's screenshot and source discovery without changing Guinness:

npm run guinness:des2code-code-import -- \
  --dry-run \
  --include '<story-filter>' \
  --limit-components 1

The dry run does not call the Guinness API. It may still build or start Storybook and write local screenshots and manifests needed for discovery.

After the dry run passes, test one real component import:

npm run guinness:des2code-code-import -- \
  --include '<story-filter>' \
  --limit-components 1

Check that component processing reaches completed, variation requests are accepted without submission failures. The importer does not poll the variation workers after their requests return 202 Accepted.

Run the full import

npm run guinness:des2code-code-import

The command performs the complete workflow:

1. Discovers Storybook stories under the configured component root.
2. Reuses existing screenshots and captures only missing story screenshots.
3. Groups stories by component source.
4. Imports each component's implementation, local styles, and preview screenshot.
5. Waits for each asynchronous component import to complete.
6. Imports successful story screenshots as code variations.

Component IDs are deterministic and the default mode is upsert, so the command is safe to rerun.

Check the result

Review the final report:

des2code-code-import/output/import-report.json

It records the target organization and project, discovered and imported counts, component failures, and variation submission failures. Screenshots and their manifest are stored under des2code-code-import/output/screenshots/.

Rebuild the index separately

Imports do not rebuild the code index. Run this command after component and variation processing has finished. The command queues a rebuild; it does not verify worker completion.

# Run after variation processing has finished.
npm run guinness:des2code-code-import -- --rebuild-index-only

Useful options

Option	Purpose
--components-dir <path>	Override the component root
--include <regexp>	Filter by story title, ID, name, or import path
--limit-components <n>	Import only the first n matching components
--mode <upsert\|create\|skip-existing>	Select how existing components are handled
--reuse-manifest <path>	Reuse screenshots from another manifest; may be repeated
--strict-screenshots	Fail the import when any Storybook screenshot fails
--skip-variations	Import components without their rendered variations
--rebuild-index-only	Queue a code-index rebuild without importing
--dry-run	Discover and validate without calling Guinness

To recapture all Storybook screenshots instead of reusing existing files:

npm run gen:storybook-screenshots -- --no-skip-existing

For the worker processing contract, see AI Code Import.