DOCSEARCHbyAlgolia
Submit Docs

Claude Artifact Runner

repository·main·Indexed 20 days ago

https://github.com/claudio-silva/claude-artifact-runner

A zero-config utility (version 2.0.0) that transforms Claude AI-generated Artifacts into deployable React applications. It provides a CLI via npx or Docker to run, build, or scaffold full development projects from single .tsx or .jsx files. The tool supports React 18, TypeScript, Vite, Tailwind CSS, Shadcn UI, Recharts, Lucide React, and Three.js.

Tokens
11.3K
Snippets
39
Records
51
Agent score
67%

What's inside claude-artifact-runner

  1. Project Directory Structure

    main

    Understanding the project layout is essential for managing artifacts and builds:

    • src/artifacts/: Place Claude-generated artifacts here.
    • dist/: Contains the compiled production output.
    • src/: Application source code.
    • src/components/: Bundled Shadcn UI components.
    • src/main.tsx: The application entry point.
    • public/: Standalone static assets.
    • src/assets/: Static assets used by the build system.
    • index.html: The entry HTML file.

  2. Use Cases for Claude Artifact Runner

    main

    The tool is designed for several developer workflows:

    • Local Execution: Run Artifacts on your machine or a web server.
    • Project Scaffolding: Use an Artifact as the foundation for a new, extensible web application.
    • App Composition: Combine multiple Artifacts into a single multi-page application using file-based routing.
    • Automation: Integrate the npx command into CI/CD pipelines.
    • Dynamic Hosting: Build an 'Artifact Creator' web app that uses this command to dynamically run or download user-generated Artifacts.

  3. What are Claude Artifacts?

    main

    Artifacts are interactive web applications generated by Claude AI. They are typically provided as raw code (which you can copy or download) rather than a complete, runnable web project.

    This project bridges the gap by providing the necessary tooling, dependencies (like React, Tailwind CSS, and Shadcn UI), and build processes to transform that raw code into a standalone, deployable web application or a full-scale development project.

  4. Expand ESLint configuration for production applications

    main

    To enable type-aware lint rules for production-grade development, you must update your ESLint configuration to include parserOptions that point to your TypeScript configuration files.

    Follow these steps:

    1. Configure the parserOptions property in your ESLint config file to include project and tsconfigRootDir.
    2. Update your extends list to use type-checked TypeScript rules instead of standard recommended rules.
    3. (Optional) Add stylistic type-checked rules.
    4. (Optional) Install and add eslint-plugin-react for React-specific linting.
    export default {
  // other rules...
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: ['./tsconfig.json', './tsconfig.node.json'],
    tsconfigRootDir: __dirname,
  },
  extends: [
    'plugin:@typescript-eslint/recommended-type-checked',
    'plugin:@typescript-eslint/stylistic-type-checked',
    'plugin:react/recommended',
    'plugin:react/jsx-runtime'
  ],
}

  5. Build an Artifact for deployment

    main

    Use the build subcommand to generate production-ready files from a .tsx or .jsx artifact.

    Build Types:

    • Single-file (Default): Generates a single HTML file. The favicon is embedded as a data URL.
    • Multi-file: Use the -e, --expanded flag to create a multi-file deployment (includes an index.html and an assets/ directory). This is better for larger applications.

    Options:

    • --strict: Enables strict TypeScript checking during the build.
    • --deploy-dir <path>: Specifies the output directory for the built files.

    Examples:

    npx run-claude-artifact build my-app.tsx                        # Single HTML file
npx run-claude-artifact build my-app.tsx --strict               # Single HTML file with strict checking
npx run-claude-artifact build my-app.tsx --expanded             # Multi-file deployment
npx run-claude-artifact build my-app.tsx --deploy-dir /var/www  # Custom output location
    npx run-claude-artifact build my-app.tsx                        # Single HTML file (no strict checking)
npx run-claude-artifact build my-app.tsx --strict               # Single HTML file (with strict checking)
npx run-claude-artifact build my-app.tsx --expanded             # Multi-file deployment
npx run-claude-artifact build my-app.tsx --deploy-dir /var/www  # Custom output location

  6. Quick Start with run-claude-artifact

    main

    You can use the run-claude-artifact CLI tool via npx to quickly interact with Claude AI Artifacts. Depending on your goal, use one of the following commands:

    • Run an Artifact: Instantly run a single .tsx file locally.
    • Build an Artifact: Generate a deployable single-file or multi-file output.
    • Create a Project: Scaffold a full, editable React + TypeScript + Vite project from an Artifact.
    • Run via Docker: Execute the runner inside a container if you prefer not to use npx.
    # Run an Artifact
npx run-claude-artifact my-app.tsx

# Build for deployment (single-file by default)
npx run-claude-artifact build my-app.tsx

# Create a full editable project
npx run-claude-artifact create my-app.tsx

# Run an artifact using Docker instead of npx
docker run --rm -p 5173:5173 -v $(pwd):/w -w /w claudiombsilva/claude-artifact-runner my-app.tsx

  7. Build for Production: Single-file vs Multi-file

    main

    You can choose between two build modes depending on your deployment needs:

    Single-file deployment

    Best for small, single-page applications. It inlines all assets into one file.

    • Command: npm run build:single
    • Strict mode (with TypeScript validation): npm run build:single:strict (Note: may flag valid AI-generated code as errors).

    Multi-file deployment

    Best for larger applications. It generates separate optimized files for each asset and page, allowing for better caching and faster initial loads.

    • Command: npm run build
    • Strict mode (with TypeScript validation): npm run build:strict

    Note: Multi-file builds cannot be viewed by opening dist/index.html directly in a browser due to security restrictions. Use a local server like npx serve dist to preview them.

    # Single file build
npm run build:single

# Multi-file build
npm run build

# Strict builds (with type checking)
npm run build:strict
npm run build:single:strict

  8. Customizing a complex application

    main

    For advanced users wanting to move beyond simple Artifacts, the project supports full customization:

    Styling

    • Tailwind CSS: Use Tailwind classes directly in components. Modify tailwind.config.mjs for theme customization.
    • Global Styles: Use src/index.css for critical global styles.
    • Component Styles: Use CSS Modules (*.module.css) or CSS-in-JS solutions like styled-components for component-specific or dynamic styling.

    Assets and Layout

    • Static Assets: Place images and other assets in the public folder.
    • Layouts: Modify main.tsx to implement custom layouts like navigation bars, sidebars, or headers.
    • Components: Add or modify components in src/components/.

    Managing Dependencies

    • Shadcn UI: Components are located in src/components/ui. You can add new ones using npx shadcn-ui@latest add <component-name>.
    • Optimization: To reduce bundle size, you can remove unused libraries (like Recharts) using npm remove <package-name> or delete unused Shadcn UI files from src/components/ui.

  9. Build a Claude Artifact for deployment

    main

    You can compile an Artifact into a standalone file for hosting. There are two build modes:

    Single-file build

    Generates a single HTML file containing all code (HTML, CSS, JS) and a favicon. This is ideal for static hosting or opening directly from the filesystem (file:// protocol).

    npx run-claude-artifact build <path-to-file>

    Multi-file build

    Use the -e flag to generate a build with separate files (e.g., separate CSS/JS). This mode requires a local web server to view due to browser security restrictions regarding file:// URLs.

    npx run-claude-artifact build <path-to-file> -e
    npx run-claude-artifact build <path-to-file>

  10. Run an artifact using Docker

    main

    You can use the claudiombsilva/claude-artifact-runner Docker image as an alternative to npx run-claude-artifact. This is ideal for CI/CD pipelines or environments without a local Node.js installation.

    To run an artifact with a dev server, you must:

    1. Mount your workspace: Use -v $(pwd):/w -w /w to allow the container to read your source files and write output back to your host.
    2. Map the port: Use -p 5173:5173 to access the Vite dev server at http://localhost:5173/.

    The container automatically applies --no-open --public flags to ensure the server binds to 0.0.0.0 and doesn't attempt to open a browser inside the container environment.

    # Run an artifact (with port mapping for dev server)
docker run --rm -p 5173:5173 -v $(pwd):/w -w /w claudiombsilva/claude-artifact-runner my-app.tsx

  11. Quick Start with run-claude-artifact via npx

    main

    The run-claude-artifact package allows you to run, build, or create full projects from a single React/TypeScript artifact file using npx. It clones a template, injects your code, and sets up a Vite-based environment.

    Basic Syntax:

    npx run-claude-artifact [run|view|build|create] <src-file> [options]

    Argument Types:

    • <src-file>: A path to a .tsx or .jsx file (for run, build, or create) or a .html file/directory (for view).
    npx run-claude-artifact my-app.tsx

  12. Prerequisites for installation

    main

    To use the npx commands, ensure your environment meets these requirements:

    • Node.js: Minimum version 20 (LTS/Iron). Version 22.11 is recommended. Tested up to 23.2.
    • npm: Usually included with Node.js.
    • npx: Included with npm 5.2+.
    • git: Required for the create command to clone templates and manage repositories.