For developers — install the Commerce Studio Drupal plugin

Northbridge Eyewear runs the Commerce Studio for Drupal plugin to power virtual try-on, eye-test booking, lens recommendations, and appointment recall. This page is the install path a retailer like Specsavers would follow to reproduce the same experience on their own Drupal 10/11 site.

1. Get plugin credentials

The plugin distributes through a private packagist endpoint (packagist.varai.ai) per ADR-0013. Customers obtain credentials from VARAi sales and add them to ~/.composer/auth.json:

{
  "http-basic": {
    "packagist.varai.ai": {
      "username": "<customer-id>",
      "password": "<customer-token>"
    }
  }
}

Demo note: the staging build uses a composer path repository pointing at the monorepo (see apps/platform-integrations/drupal/deploy/composer.json). The credentialed packagist endpoint is the planned distribution path; the path repo is the live mechanism for this demo container.

2. Install via Composer

# Add the VARAi composer repository to your project
composer config repositories.varai composer https://packagist.varai.ai

# Require the plugin
composer require varai/commerce-studio-drupal:^1.0

3. Enable the module + dependencies

drush en commerce_studio flysystem flysystem_gcs -y
drush cr

flysystem + flysystem_gcs are required for the GCS-backed file system used by VTO assets. If your site already serves files from another adapter (S3, local), the GCS modules can be left disabled.

4. Configure your tenant

Either via the admin UI at /admin/config/services/commerce-studio, or via Drush:

drush config:set commerce_studio.settings api_key <YOUR_TENANT_API_KEY> -y
drush config:set commerce_studio.settings region us -y           # or eu
drush config:set commerce_studio.settings environment production -y  # or staging

Configuration matrix

All keys live under the commerce_studio.settings config object:

Key	Type	Description
`api_key`	string	Tenant API key (`csk_*`) issued by Commerce Studio. Required.
`region`	`us` \| `eu`	Which CS regional backend serves the tenant. Default `us`.
`environment`	`production` \| `staging`	Selects the production or staging backend within the chosen region. Default `production`.
`widget_url_override`	URL	Optional. If set, bypasses service discovery and uses this URL as the VTO widget origin. For QA / pinning a specific build.
`practice_studio_base_url`	URL	Optional. The Practice Studio backend URL used by the appointment + patient blocks (P2.5+). Defaults to the regional PS endpoint.
`discovery_cache_ttl`	int (seconds)	How long the plugin caches the `/discover` response. Default 86400 (1 day).

5. Place the plugin blocks

Three plugin blocks ship today. Place each at /admin/structure/block in the appropriate region:

commerce_studio_vto_widget — virtual try-on; place on product detail pages.
commerce_studio_appointment_booking — eye-test booking; place on a /book or /eye-test page.
commerce_studio_my_appointments — appointment lookup; place on the customer account area.

6. Demo theme (optional)

The Northbridge theme you are looking at lives at apps/platform-integrations/drupal/demo-theme/varai_eyewear/ in the Commerce Studio repo. It is an Olivero sub-theme — copy it into web/themes/custom/, enable, and set as default.

What ships in Phase 3

The next plugin release (Phase 3) layers in deeper Drupal-side integration per PS PRD-0003:

Catalog sync — Drupal Commerce SKUs push to Commerce Studio so VTO + analytics resolve against the retailer’s own catalog.
Analytics events — try-on starts, completes, add-to-cart fire into analytics_events for the tenant dashboard.
Brand mirror — Commerce Studio brand records render as read-only Drupal taxonomy terms for content authoring.

Plugin source & versioning

The plugin source lives at apps/platform-integrations/drupal/module/ in the Commerce Studio monorepo. Version lockstep with Practice Studio’s contract is described in ADR-0010.

This Northbridge demo is the verification surface for the install path described above. Track demo phases at .goap-memory/drupal-eyewear-demo/PROJECT.md.