@sogody/experiment-framework

CLI that scaffolds a Vite + Preact A/B experiment project for Adobe Target. Generates a self-contained IIFE bundle per variation, wired up with @sogody/experiment-framework/framework, with clipboard copy on save so the built code can be pasted directly into Adobe Target.

Prerequisites

• Node ≥ 20.19 (recommended: 24 — see .nvmrc)
• pnpm 10.30.1

Generated projects support pnpm >=10.26.0. Node.js 20 users must use pnpm >=10.26.0 <11; pnpm 11 requires Node.js 22 or newer. This repository remains pinned to pnpm 10.30.1 for maintainer workflows.

Usage

npx @sogody/experiment-framework <project-name>

Prompts:

| Prompt | Default | Notes | |--------|---------|-------| | Window namespace | sgd | JS identifier registered on window (e.g. window.sgd) | | Emergency brake | true | Enables Adobe Target kill-switch via experiment.config.js | | Variation count | 1 | Number of variations to scaffold (v1..vN) | | E2E testing | false | Generates Playwright smoke tests when enabled |

After scaffolding, dependencies are installed automatically.

What gets generated

Generic Adobe Target / Preact experiment boilerplate with a locale-aware button component:

<project-name>/
  src/
    components/
      ExperimentButton/
        index.jsx
        styles.module.scss
    js/
      v1/                   # Variation 1 entry point
        index.jsx           # runScript → render → track
      v2/                   # Additional variations (when variationCount > 1)
    config.js               # selectors, buttonText
  # Runtime/build/new-variation tooling is provided by
  # @sogody/experiment-framework dependency via exp-* binaries
  experiment.config.js      # runtime globalObject, emergencyBrake, targetUrl
  vite.config.js            # IIFE lib mode, Preact bundled, legacy aliases, CSS Modules
  biome.json                # JS/JSX formatter + linter

Dev workflow

pnpm start 0        # watch v1 — rebuilds on save, copies bundle to clipboard
pnpm start          # watch all variations
pnpm dev            # watch all variations
pnpm build          # production IIFE bundles → dist/vN-index.jsx
pnpm live           # runs package-owned exp-live; opens targetUrl and injects the watched variation
pnpm live -- --profile shared  # reuse one OS cache profile across experiments
pnpm add-e2e        # add Playwright E2E setup to an existing generated project
pnpm init-claude    # create CLAUDE.md on demand
pnpm init-agents    # create AGENTS.md on demand
pnpm lint           # Biome for JS/JSX/JSON

pnpm start 0 maps to src/js/v1/index.jsx, pnpm start 1 to v2, and so on. The clipboard copy keeps development logging enabled so you can paste and debug in Adobe Target's custom code editor. Production output uses pnpm build and the legacy flat shape, for example dist/v1-index.jsx.

CSS Modules class prefix is auto-derived from the project folder name (sanitized), so no extra CLI prompt is required. Generated class names use the legacy separator, for example project-name--button.

CSS is compiled by Vite with Sass support. Generated projects do not include Stylelint or cssnano; production CSS minification uses Vite's built-in esbuild CSS minifier.

Generated Vite config includes legacy import aliases: @src, @js, @components, @services, and @helpers. Build and live commands read experiment.config.js first and fall back to legacy config.json.

Runtime helpers from @sogody/experiment-framework/framework include legacy-compatible exports such as runScript, withPreact, waitForJquery, domReady, createElementFromHTML, setCookie, getCookie, emergencyBrakeEnabled, and classes. withPreact is a compatibility shim because Preact remains bundled.

AI documentation is opt-in. The init commands infer E2E setup from the project, and refuse to overwrite existing files unless passed -- --force. After upgrading @sogody/experiment-framework in an older generated project, run the binaries directly with pnpm exec exp-init-claude or pnpm exec exp-init-agents.

Adding E2E Tests Later

Generated projects include an add-e2e script:

pnpm add-e2e

For older projects that do not have that script yet, run the package binary directly:

pnpm exec exp-add-e2e

Options:

• --force replaces generated E2E source files when a partial setup already exists.
• --dry-run prints planned file changes and commands without writing files.
• --yes accepts the default base URL and UK market.
• --skip-install skips dependency installation.
• --run-smoke runs pnpm test:e2e after setup.

pnpm add-e2e does not install Playwright browsers. If the first smoke run reports missing browsers, install them on demand with pnpm playwright install.

Adding a variation

pnpm new-variation 2          # scaffolds src/js/v2/ from v1
pnpm new-variation control    # scaffolds src/js/control/ from v1

Then update selectors, props, and tracking label in the new src/js/*/index.jsx entry and run pnpm build. The start command uses zero-based indexes. Numeric variation folders are ordered first, then named folders such as control.

Tracking

Use setupTracking after Preact render so the rendered element exists. The scaffold defaults to eVar26 and event26; set selector to match the rendered control:

setupTracking(container, {
    label: 'experiment-name: v1 button clicked',
    selector: 'button',
});

CI

No CI pipeline is configured yet. Run pnpm test locally before opening a PR.

Release handoff

Maintainers should publish with Node 24 and pnpm 10.30.1:

nvm use 24
pnpm install
pnpm release:check
npm view @sogody/experiment-framework version
pnpm publish --access public

If npm view @sogody/experiment-framework version returns 404 Not Found, the scoped package is not currently published or is not visible to the current account. Confirm package-name ownership before publishing. If local npm cache permissions block npm pack, rerun the pack check with a temporary cache:

npm --cache /tmp/experiment-framework-npm-cache pack --dry-run

Contributing

nvm use 24            # match .nvmrc
pnpm install
pnpm test             # run integration tests before committing

Migration Note

pnpm build approvals

Projects generated with the old pnpm approval format should:

1. Remove package.json.pnpm.onlyBuiltDependencies.
2. Change engines.pnpm in package.json to >=10.26.0.
3. Add pnpm-workspace.yaml:

allowBuilds:
  '@biomejs/biome': true
  '@parcel/watcher': true
  esbuild: true
strictDepBuilds: true

This migration is intentionally manual so existing project-specific approvals are not overwritten.

Package scripts

If you generated a project with older package conventions, replace these script names in your generated project:

• sogody-start -> exp-start
• sogody-build -> exp-build
• sogody-new-variation -> exp-new-variation