CI/CD Pipeline

What this covers

This document describes how a Laioutr app moves from local development through CI/CD into production. An "app" is a Laioutr Nuxt module distributed as an npm package.

System overview

1. A developer builds or updates an app locally.
2. The app is published as an npm package via the team's CI/CD pipeline.
3. The version is registered with the Laioutr platform via the CLI.
4. A deployment is triggered — either to production or a preview environment.

The app pipeline (owned by the customer/team) handles building and publishing. Deployment is triggered via the Laioutr CLI, which orchestrates the build and deploy through the platform's hosting infrastructure.

1. App development

Start with the official App Starter and follow the Local Development Setup guide to configure your environment.

An app provides:

• A Nuxt module entry point (src/module.ts)
• Orchestr handlers — queries, actions, links, resolvers, and query templates — under src/runtime/server/orchestr/
• Sections and blocks under src/runtime/app/sections/ and src/runtime/app/blocks/

The package.json "name" defines the package identity and is used as the config key in laioutrrc.json.

2. Building and publishing the npm package

Each team owns their app CI/CD pipeline. It typically runs in your Git provider (GitHub Actions, GitLab CI, Azure DevOps, etc.) and should:

1. Trigger on pushes to main or on release branches/tags.
2. Install dependencies and build the Nuxt module (pnpm install, pnpm build, or equivalents).
3. Enforce quality gates — linting, tests, optional type-check and bundle size checks.
4. Version the package (manual or via tools such as Changesets).
5. Publish to an npm registry — npm.laioutr.cloud for private packages, or npmjs.org for public packages.

3. Registering versions with Laioutr

After publishing the npm package, register the new version with the platform:

laioutr app publish --key orgKey_xxx

This extracts the config schema from src/module.ts, reads version and peer dependencies from package.json, and registers the version in the Cockpit. Pre-release versions are assigned to the testing channel automatically.

Run this as a CI/CD step after npm publish, or manually from the package directory.

4. Project configuration

Apps are configured per-project in laioutrrc.json. Each entry specifies the package name, version, and app-specific configuration:

{
  "apps": [
    {
      "name": "@laioutr-app/ui",
      "version": "latest",
      "config": {
        "theme": "sunny"
      }
    },
    {
      "name": "@laioutr-app/shopify",
      "version": "latest",
      "config": {
        "shopId": "84306067782",
        "storeDomain": "my-store.myshopify.com",
        "publicAccessKey": "074478fbce..."
      }
    },
    {
      "name": "@laioutr-org/acme__my-app",
      "version": "latest",
      "config": {}
    }
  ]
}

Configuration can also be managed through the Cockpit UI under project settings.

5. Deploying

Trigger deployments using the Laioutr CLI:

# Production deployment
laioutr deploy trigger --project org/project --key orgKey_xxx

# Preview deployment with app version overrides
laioutr deploy trigger \
  --project org/project \
  --key orgKey_xxx \
  --preview my-feature \
  --with-app @laioutr-app/[email protected]

Preview deployments create ephemeral environments for testing new app versions without affecting production. The --with-app flag overrides the installed version for that single deployment.

Example: shipping a new app from scratch

Assuming you have created an app using the App Starter and developed it locally:

# 1. Push your code
git push origin main

# 2. CI/CD builds and publishes (e.g. in GitHub Actions)
pnpm install && pnpm build && npm publish

# 3. Register the version with Laioutr
laioutr app publish --key orgKey_xxx

# 4. Deploy a preview for QA
laioutr deploy trigger \
  --project acme/storefront \
  --key orgKey_xxx \
  --preview test-my-app \
  --with-app @laioutr-org/[email protected]

# 5. Once tested, deploy to production
laioutr deploy trigger --project acme/storefront --key orgKey_xxx