How to Configure build-web-apps for Deployment Workflows

Configure build-web-apps for deployment workflows by running a front-end builder skill to generate a React+Vite codebase, then invoking a platform-specific deployment skill (such as Vercel, Netlify, or Catalyst-by-Zoho) that accepts the generated project folder as input.

The build-web-apps plugin in the OpenAI Plugins repository provides a complete toolkit for generating production-ready front-end applications and deploying them to modern hosting platforms. Unlike monolithic deployment tools, this plugin separates code generation from hosting operations, allowing you to pair its React and Vite scaffolding with any compatible deployment provider. Understanding how to wire these components together ensures your automated workflows produce live sites that match your design specifications.

Understanding the build-web-apps Deployment Architecture

The plugin follows a strict separation of concerns between building and deploying. According to the source code in plugins/build-web-apps/.codex-plugin/plugin.json, the plugin exposes builder skills that generate source files, assets, and design systems, but delegates actual hosting operations to external deployment plugins.

The typical workflow involves two distinct phases:

1. Front-end generation – Skills like frontend-app-builder, react-best-practices, or shadcn-best-practices create a complete codebase in a designated output folder.
2. Platform deployment – A separate deployment skill reads the generated package.json, installs dependencies, runs npm run build, and executes platform-specific CLI commands (e.g., vercel deploy).

This architecture allows the build-web-apps plugin to remain hosting-agnostic while supporting verified deployment targets through the plugin ecosystem.

Step-by-Step Configuration Guide

Install and Verify the Plugin

The build-web-apps plugin resides in the OpenAI Plugins repository at plugins/build-web-apps. No additional installation is required beyond ensuring the plugin manifest at plugins/build-web-apps/.codex-plugin/plugin.json is present in your environment. This manifest defines the plugin interface and available skill endpoints.

Select a Front-end Builder Skill

Choose a builder skill that matches your project requirements. The primary skill, frontend-app-builder, is defined in plugins/build-web-apps/skills/frontend-app-builder/SKILL.md. For specialized stacks, use practice-specific skills such as:

• react-best-practices for React-specific optimizations
• shadcn-best-practices for component library integration
• stripe-best-practices for payment workflow scaffolding
• supabase-best-practices for backend integration

These skills generate the project folder containing package.json, source files, and a README describing the design system.

Configure the Deployment Target

Select a deployment skill corresponding to your hosting provider. The build-web-apps plugin does not contain deploy logic internally; instead, it expects another installed plugin that implements the target platform. Common options include:

• Vercel – Located in plugins/vercel/skills/deployments-cicd/
• Netlify – Available in the Netlify plugin directory
• Catalyst-by-Zoho – For Zoho Catalyst deployments

Each deployment skill contains platform-specific CLI wrappers and CI/CD reference documentation.

Execute the Hand-off Workflow

After the builder skill completes, pass the generated project path to your chosen deployment skill. The deployment skill performs the following operations:

1. Reads the project's package.json to identify build commands
2. Runs npm install to restore dependencies
3. Executes npm run build to create the production bundle
4. Invokes the platform CLI (e.g., vercel deploy --prod)

This hand-off mechanism is documented in the builder skill's verification routine, which includes view_image comparison logic to ensure visual fidelity between the generated design and deployed site.

Automate in CI/CD Pipelines

Add the builder and deployment commands to your continuous integration configuration. The deployment skills are designed to run headlessly, requiring only the OpenAI Plugins SDK and appropriate environment variables (such as VERCEL_TOKEN for Vercel deployments).

Code Examples

Generate a React Application

Use the frontend-app-builder skill to scaffold a new project with specific sections:

openai plugins build-web-apps frontend-app-builder \
    --project-name my-site \
    --sections home,features,pricing \
    --output ./generated-my-site

This command creates ./generated-my-site containing a Vite-based React application, configured with your specified page sections and design system.

Deploy to Vercel

Invoke the Vercel deployment skill immediately after generation:

openai plugins vercel deployments-cicd \
    --source ./generated-my-site \
    --project my-site

The skill automatically handles dependency installation, production builds, and CLI deployment using the credentials configured in your environment.

GitHub Actions Workflow

Automate the complete pipeline using GitHub Actions:

name: Deploy Build-Web-Apps Site
on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install OpenAI Plugins SDK
        run: pip install openai-plugins
      
      - name: Build front-end application
        run: |
          openai plugins build-web-apps frontend-app-builder \
            --project-name my-site \
            --sections home,features,pricing \
            --output ./site
      
      - name: Deploy to Vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        run: |
          openai plugins vercel deployments-cicd \
            --source ./site \
            --project my-site

Replace the Vercel skill invocation with any other deployment provider by changing the plugin namespace and project identifier.

Key Files and Implementation Details

Understanding these critical source files helps debug configuration issues:

• plugins/build-web-apps/.codex-plugin/plugin.json – The plugin manifest defining available skills and interfaces
• plugins/build-web-apps/skills/frontend-app-builder/SKILL.md – Documentation for the main builder skill, including the design-first workflow and verification steps (lines 51-57 contain the view_image comparison logic)
• plugins/build-web-apps/skills/react-best-practices/README.md – Example of specialized practice skills that extend the base builder
• plugins/<provider>/skills/deployments-cicd/ – Platform-specific deployment implementations containing CLI wrappers and CI reference documentation

Summary

• Separate concerns: Use build-web-apps skills for code generation and platform-specific plugins for hosting operations.
• File locations: Key configuration resides in plugin.json and individual SKILL.md files within the skills/ directories.
• Workflow: Run frontend-app-builder (or specialized variants) first, then pass the output folder to a deployment skill like Vercel or Netlify.
• Verification: Reuse the builder's view_image comparison logic after deployment to confirm visual accuracy.
• Automation: CI/CD pipelines require only the OpenAI Plugins SDK and environment variables for the target platform.

Frequently Asked Questions

Does the build-web-apps plugin include built-in hosting?

No, the build-web-apps plugin intentionally excludes hosting logic. According to the source structure in plugins/build-web-apps/, the plugin only provides builder skills that generate React+Vite codebases. Deployment requires a separate plugin (such as Vercel, Netlify, or Catalyst-by-Zoho) that implements the specific hosting platform's CLI and API interactions.

How do I verify that my deployed site matches the design specification?

The frontend-app-builder skill includes a verification routine utilizing view_image comparison, described in lines 51-57 of plugins/build-web-apps/skills/frontend-app-builder/SKILL.md. After deployment, run this verification step to compare the live site against the accepted design spec, ensuring visual fidelity between the generated code and the production environment.

Can I use build-web-apps with custom deployment pipelines?

Yes, the plugin architecture supports custom deployment workflows. The builder skills output standard npm-based projects with package.json configurations. You can use the frontend-testing-debugging skill to generate a ready-to-publish dist/ folder, then integrate this output into any custom deployment pipeline that handles static site hosting, bypassing the official deployment plugins if needed.

What front-end frameworks does the builder support?

By default, the frontend-app-builder skill generates React applications using Vite as the build tool. Specialized skills like react-best-practices, shadcn-best-practices, stripe-best-practices, and supabase-best-practices extend this base configuration to include specific library integrations and best practices for those ecosystems, as documented in their respective README.md files under plugins/build-web-apps/skills/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}