Claude Artifact Runner

From Claude Artifact to deployable React app — in seconds!

Zero‑config npx tool and template to run, build, or create full projects from Claude AI Artifacts.

Run an Artifact in seconds, without having to create a project first and build it
Build single‑file or multi‑file outputs ready to deploy anywhere
Create a full React + TypeScript + Vite + Tailwind + Shadcn UI project
Includes additional libraries when needed: Recharts, Lucide React, and more
Combine multiple Artifacts into a multi‑page app (file‑based routing)
Run locally or deploy to any web hosting service

Quick start:

# 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

What are Artifacts and why this project?

Artifacts are interactive web applications created by Claude AI, and they are a great way to get started with web development.

They are typically created in a web browser at Claude's website, and then saved as a single file containing the main logic of the app.

Claude already provides both Copy and Download buttons for you to get the Artifact code, but it does not provide either:

the final files that are needed to run the Artifact independently,
or the full project needed to develop it further.

Note that the code loaded by your web browser to run the Artifact is not the same as the code you copy or download from the web interface; the former is a transpiled, minimized and bundled version that includes all the necessary libraries (e.g., React) required to run it (i.e. the files that result from a build process); the latter is the raw code that you can copy and paste into your own project.

If you're unfamiliar with the technologies used on the project, you'll have a hard time assembling and configuring all the required libraries and tooling required to make a running standalone app.

Even if you're an experienced developer, you may just want to save time and effort and get the Artifacts running as easily and as soon as possible.

This template project, and the accompanying npx command, provide the fastest and easiest way to get your Artifacts up and running on your machine.

It includes all the necessary dependencies and configurations to seamlessly transition your Claude-generated Artifacts into a fully functional web application in no time.

Use Cases

Run Artifacts on your local machine, on a web server or on a cloud service.
Use Artifacts as a starting point for a new project and then extend it with custom code.
Create a new web application and add some Artifacts to it.
Develop an Artifact Creator web application and use the npx command to dynamically run or download them.
Use the npx command as part of a CI/CD build pipeline.
Or don't use Artifacts at all and just use the project as a starting point for your custom coded web application.

Quick Start

If you want to just run an Artifact

Download the Artifact to your local machine, as a .tsx or .jsx file.
Run it: On the terminal, run npx run-claude-artifact <path-to-file>
Wait a few seconds. A browser window or tab will open and you'll see your Artifact running. When finished, press Ctrl+C on the terminal to stop the preview server.

If you don't have an Artifact to run yet, and just want to try out the project, run npx run-claude-artifact with no arguments to see a demo.

If you want to build an Artifact

Download the Artifact to your local machine, as a .tsx or .jsx file.
Build it: On the terminal, run npx run-claude-artifact build <path-to-file>

The tool outputs an HTML file in your current directory, which contains all the code for running the application (HTML, CSS, JavaScript and a favicon).

This file can be deployed to any static web hosting service or cloud platform.

If you want to view a previously built Artifact

There are two build types, with different preview methods:

Single-file builds (e.g., npx run-claude-artifact build <file>, as explained above):
- Can be opened directly from the filesystem (double-click the HTML file or open the URL file://path/to/file.html).
- Multiple pages are supported via HashRouter, so navigation works under file://.
Multi-file builds (e.g., npx run-claude-artifact build <file> -e):
- Require a local web server to view them because additional files (like CSS and JavaScript files) cannot be loaded from the filesystem directly (file:// URLs) because of browser security restrictions.
- Use the view subcommand to preview locally:
  - npx run-claude-artifact view artifact-directory-name (serve the directory)
  - The tool launches a temporary web server and opens your browser. Press Ctrl+C to stop.

If you want to create a full project for one or more Artifacts

Instead of just viewing or building an Artifact, you may create a full project for further development, and optionally push it to your own Git repository.

Built with modern web development essentials including TypeScript, Tailwind CSS, Shadcn UI, and file-based routing, this pre-configured setup lets you focus on development rather than configuration. As a standard React application, you have the freedom to extend it with any features you need, from backend services like Supabase to web frameworks such as Express, Fastify or Hono.

You can blend AI-generated Artifacts with your own custom code, incorporate code generated by other AI tools, such as v0.dev, or even build applications without any Artifacts at all and just start with a base project template to power your custom development.

You'll be able to deploy your app anywhere, whether locally for your own use, in a company intranet or in a public-facing production environment, at the webhosting or cloud provider of your choice.

See the Installation section below for detailed installation instructions and advanced options.

Limitations

This project is meant for running Artifacts that are interactive web apps, usually made in React, and for which Claude writes Javascript or Typescript code.

Mermaid diagrams, SVGs, and other document-type Artifacts are out of the project’s scope.

Also, Claude's Artifacts run client-side only (i.e. in the browser). As such, they are limited in their capabilities.

If you need a full-stack application (with database, APIs, etc.), I'll be honest, this is not the best project for that, as it does not provide a backend.

Nevertheless, it does provide a good starting point. You can still add a server-side framework to create a full-stack application, or use a cloud Backend service like Supabase or Firebase.

What's included?

These are the libraries and frameworks this project provides, identical* to those available on Claude's Artifacts environment:

React 18 for building user interfaces.
TypeScript to support Artifacts written in type-safe Javascript.
Vite for fast development and building.
Shadcn UI for pre-built, customizable components.
Tailwind CSS for compact and expressive embedded styling.
Recharts for creating dynamic, customizable charts and data visualizations.
Lucide React for a comprehensive library of open-source icons designed for React applications.

* Note that the actual versions of the packages currently in use in the Artifacts environment may differ from the ones installed by this project, as Anthropic may update them from time to time.
If a component generated by Claude fails to run properly because of an outdated package, please let me know.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js minimum supported version is 20 (lts/iron), tested up to version 23.2, version 22.11 is recommended
npm (usually comes with Node.js)
npx (comes with npm 5.2+ and higher)
git (required for project creation and optional repository creation)

Installation

Start by downloading your Artifact to your local machine, as a .tsx or .jsx file.

Command Syntax

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

Arguments:

<src-file>: Path to a .tsx/.jsx file (for run/build/create) or .html file/directory (for view)

Subcommands:

run (default): Run artifact in development server
view: Serve a built HTML file or directory
build: Build and output files
create: Create full editable project

Subcommands

Subcommand	Description
`run` (default)	Run artifact in development server
`view`	Serve a built HTML file or directory
`build`	Build and output files
`create`	Create full editable project

Basic Usage

Run Artifact (Default)

npx run-claude-artifact my-app.tsx                         # Run dev server (default)
npx run-claude-artifact run my-app.tsx                     # Same as above
npx run-claude-artifact run my-app.tsx --build             # Build single-file and run preview
npx run-claude-artifact run my-app.tsx --build --expanded  # Build multi-file and run preview
npx run-claude-artifact run my-app.tsx --build --strict    # Build with strict checking

Build Artifact

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

View Built Artifact

npx run-claude-artifact view my-app.html  # Serve single-file application
npx run-claude-artifact view my-app       # Serve directory with multi-file application

Create Project

npx run-claude-artifact create my-app.tsx                        # Create editable project
npx run-claude-artifact create my-app.tsx --remote <url> --push  # Create + git + push

Options by Subcommand

Run Subcommand Options

--build: Build project and run preview server instead of dev server
--strict: Enable strict TypeScript checking during build (requires --build)
-e, --expanded: Create multi-file build instead of single-file (requires --build)

Build Subcommand Options

-e, --expanded: Create multi-file deployment instead of single HTML
--deploy-dir <path>: Output directory for built files
--strict: Enable strict TypeScript checking during build

Create Subcommand Options

--project-dir <path>: Target directory for the project
--remote <url>: Git remote repository URL
--push: Push to remote repository after creation

Global Options

-h, --help: Show this help message

All Command Line Options

Option	Applicable To	Description
`--build`	`run`	Build project and run preview server instead of dev server
`--strict`	`run`, `build`	Enable strict TypeScript checking during build
`--expanded, -e`	`run`, `build`	Create multi-file build instead of single-file
`--deploy-dir <path>`	`build`	Output directory for built files
`--project-dir <path>`	`create`	Target directory for the project
`--remote <url>`	`create`	Git remote repository URL
`--push`	`create`	Push to remote repository after creation
`--help, -h`	All	Show help message

Execution Workflow

The script follows different sequences based on the subcommand:

`run` Subcommand (default)

Clone & Setup → Clone template, remove .git/npx, copy your artifact
Run/Preview → Start dev server (or build + preview if --build used), open in browser, block until Ctrl+C
Cleanup → Remove temporary directory

`build` Subcommand

Clone & Setup → Clone template, remove .git/npx, copy your artifact
Build → Build project (with --expanded affecting build type) - abort on failure
Deploy → Copy built files to output directory
Cleanup → Remove temporary directory

`view` Subcommand

Start Server → Launch web server to serve the specified HTML file
Block → Run until Ctrl+C

`create` Subcommand

Clone & Setup → Clone template, remove .git/npx, copy your artifact
Create Project → Move full project to target directory
Git Setup → Initialize repository, add remote, commit, push if requested
Cleanup → Remove temporary directory

Subcommand Flow Matrix

Subcommand	Input	Output	Server	Blocks?	Purpose
`run` (default)	`.tsx`/`.jsx`	❌	✅ Dev/Preview	✅	Interactive testing
`build`	`.tsx`/`.jsx`	✅ Files	❌	❌	Generate deployment files
`view`	`.html`	❌	✅ Static	✅	Serve built files
`create`	`.tsx`/`.jsx`	✅ Project	❌	❌	Development workspace

Deployment Directory Logic (for `build` subcommand)

Build Type	--deploy-dir	Default Path	Output
Single file	❌	Current Working Directory	`CWD/my-app.html`
Single file	✅	`/path/to/deploy`	`/path/to/deploy/my-app.html`
Multi-file	❌	CWD + filename	`CWD/my-app/index.html` + `CWD/my-app/assets/`
Multi-file	✅	`/path/to/deploy`	`/path/to/deploy/index.html` + `/path/to/deploy/assets/`

Notes

Git is always required (for initially cloning the template)
Single-file builds embed the favicon as a data URL; multi-file builds keep public/favicon.ico in the output and reference it normally

Alternative Methods of Installation

Using GitHub CLI

gh repo create my-project-name --template claudio-silva/claude-artifact-runner --private --clone
cd my-project-name
# Replace the demo artifact with your own
cp path/to/your-artifact.tsx src/artifacts/index.tsx
npm run dev

Create from a GitHub Template

Best for: Creating a GitHub repository for your project without using the npx command.

Go to github.com/claudio-silva/claude-artifact-runner
Click the green "Use this template" button
Choose "Create a new repository"
Name your repository and choose visibility settings

Clone your new repository:

git clone https://github.com/yourusername/your-repo-name.git
cd your-repo-name
npm install
npm run dev

Fork and Clone (Not Recommended)

Note: Forking is generally not recommended unless you plan to contribute back to the original project, as it maintains a connection to the upstream repository.

If you do fork:

Fork the repository on GitHub
Clone your fork
Consider unlinking from upstream if you don't plan to contribute back:
```
git remote remove upstream  # Remove connection to original repo
```

After installation

The default app is composed of two demo components: a login form and a signup form. You can navigate between them by clicking on the link at the bottom of the form.

These demo pages/components are just for demonstration purposes and can be easily replaced with your own components, either generated by Claude or created by yourself.
This will NOT be the UI of your application.

Installing a single Artifact

If you have created a project and you want to install or update an Artifact on it, you can follow these simple steps:

Make sure the development server is running. If not, start it by running npm run dev.
Leave the browser open at the initial page and leave the development server running.
Delete the files in the src/artifacts/ directory.
Download your Artifact from Claude.ai
Move the file to the src/artifacts/ directory and rename it to index.tsx.
You'll immediately see your Artifact running on the open browser tab.

You'll be viewing the app in development mode. To generate the final app, ready for production, you'll need to build it first:

Use npm run build to generate the release files.
Or use npm run build:single to generate a single file containing the entire application.
You'll find the built files in the dist/ directory.

Creating a multi-page application

If you want to create a multi-page application, you can follow these steps:

Follow the previous section's steps.
Generate more Artifacts using Claude and download them to the src/artifacts/ directory.
Give each file it a unique name, such as your-component.tsx. Each component you add will be a new page accessible at http://localhost:5173/your-component-name (without the .tsx extension).
If you have npm run dev running in the background, the new pages will be ready to display immediately. If a page is already open when being updated, it will refresh automatically.
You can link Artifacts to each other to build a multi-page application.

It's easy: on each Artifact page, just add links that navigate to the other Artifacts, by specifying their names without the .tsx extension.
E.g. <a href="my-component">Go to My Component</a>
You can also use the useNavigate hook to navigate to a specific page.
Finally, to create a release build and publish your finished application, follow the instructions further below.

Developing a more complex application

If you intend to create a more advanced application, you'll probably want to customize its visual appearance by changing styles, adding images and new components, creating a base layout with a top header and a sidebar with the main navigation menu, etc.

This section is intended for advanced users only, and is not required for simple applications.

Customization

For styling:
- Prefer using Tailwind classes directly in components.
- Use src/index.css only for Tailwind configuration and critical global styles.
- For component-specific styles, use CSS Modules (*.module.css).
- For complex styling needs (such as dynamic styles), consider styled-components or other CSS-in-JS solutions.
- Modify tailwind.config.mjs to customize the Tailwind CSS theme.
Place static assets (such as images) in the public folder.
Update main.tsx to change the overall layout of the app (e.g. adding a navigation bar).
Add or modify components in the src/components/ directory.

Note: Shadcn UI components installed via npx are automatically placed in src/components/ui. All components come pre-installed by default, but if you remove some and later want to reinstall any, you may simply run npx shadcn-ui@latest add <your-component>.

Removing unneeded components / libraries

The Recharts library and ALL Shadcn UI components come pre-installed, so that all code that Claude may generate will run out-of-the-box.

If you just want to run the Artifact locally, you may leave things as they are, but if you want to deploy the application or use it as a base for a larger project, you may want to optimize the application's bundle size.

To do that, you may remove the pre-installed components or libraries that are not required by your application.

Unneeded Shadcn UI components:

Just delete the component's files from src/components/ui.

Unneeded packages (ex: Recharts):

Use npm remove to uninstall them.

Project structure

Directory/File	Description
`dist/`	Compiled output
`public/`	Standalone static assets
`src/`	Contains the source code for the application
`src/artifacts/`	The Artifacts generated by Claude should be placed here
`src/assets/`	Static assets for the build system
`src/components/`	Bundled Shadcn UI components
`src/lib/utils.ts`	Utility functions and helpers
`src/index.css`	Tailwind styles
`src/main.tsx`	Entry point of the application
`src/vite-env.d.ts`	Type definitions for Vite
`.eslintrc.cjs`	ESLint configuration
`components.json`	Shadcn UI components configuration
`index.html`	Entry HTML file
`jsconfig.json`	JSON configuration
`postcss.config.js`	PostCSS configuration
`tailwind.config.mjs`	Tailwind CSS configuration
`tsconfig.app.json`, `tsconfig.json`, `tsconfig.node.json`	TypeScript configuration
`package.json`	All the required packages are registered here
`vite.config.ts`	Vite configuration

Building for production

Single file deployment

For smaller applications with one page, or just a few pages, you may build the application as a single file. Run:

npm run build:single

This will generate a single file in the dist/ directory, ready for deployment.

Building with strict checking

If you want to build a single file with rigorous code validation, run:

npm run build:single:strict

This will catch more errors and warnings during the build process, but sometimes, it may also flag valid code as errors if code is not written in a specific way.

Disabled by default, since many AI-generated artifacts fail strict checks, despite working fine in normal mode.

You can also catch more potential errors if you run a linter before building. Run:

npm run lint

Multi-file deployment

To create a production build as a set of separate files for each asset and each page, run:

npm run build

This will generate optimized files in the dist/ directory, ready for deployment.

Remember that you cannot run a multi-file application by opening the dist/index.html file directly from the filesystem to view it, as the browser will block it due to security restrictions. You need to use a local web server (e.g. run npx serve dist).

Why would you want to do build this way, instead of building a single file?

Because a multi-file build offers several advantages for larger applications:

Faster initial load times - Only the required files for the current page are loaded
Better caching - Shared resources (like common libraries) are cached separately
Progressive loading - Users can interact with parts of the app while other resources load
Smaller updates - When making changes, only modified files need to be redeployed
Better error isolation - Issues in one page won't block the entire application

Multi-file deployment with strict checking

If you want to build a multi-file application with rigorous code validation, run:

npm run build:strict

You can even catch more potential errors if you run a linter before building. Run:

npm run lint

Deploying your application

After running npm run build, you'll have a dist folder containing the built files (typically an HTML file, a JavaScript file, and a CSS file).

Here are several ways to deploy these files:

Local test deployment

For local testing of the production build, you can also use the serve npx package:

Navigate to your project directory and run:
```
npx serve -s dist
```
Open a browser and go to http://localhost:3000 (or the URL provided in the terminal).

Traditional web hosting

If you want to deploy to a shared or dedicated web server:

Upload the contents of the dist folder to your web server's public HTML directory (often called public_html, www, or htdocs).

Remember to update any necessary configuration files (like vite.config.ts) before building your app if it is not being served from the root of your domain.

For example, for vite.config.ts, you may configure it like this:

export default {
  base: '/subdirectory/', // Set this to the path your app is served from
  // other configurations
};

Cloud hosting platforms

Here are some popular free cloud hosting platforms and how to deploy your app to them:

Remember to run npm run build before deploying to ensure you're uploading the latest version of your app.

Netlify

Install the Netlify CLI:
```
npm install -g netlify-cli
```
Run the following command in your project directory:
```
netlify deploy
```
Follow the prompts. When asked for the publish directory, enter dist.
For production deployment, use:
```
netlify deploy --prod
```

Vercel

Install the Vercel CLI:
```
npm install -g vercel
```
Run the following command in your project directory:
```
vercel
```
Follow the prompts. Vercel will automatically detect that it's a Vite project and use the correct settings.

GitHub Pages

If you haven't already, create a GitHub repository for your project.
Install the gh-pages package:
```
npm install gh-pages --save-dev
```

Add these scripts to your package.json:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

Run:
```
npm run deploy
```
Set up GitHub Pages in your repository settings to use the gh-pages branch.

Cloudflare Pages

You can deploy to Cloudflare Pages either through the Cloudflare dashboard or using the wrangler CLI tool. Here's how to do it using wrangler, which is often the most straightforward method:

Install Wrangler:
```
npm install -g wrangler
```
Login to Cloudflare:
```
wrangler login
```
Deploy your project:
```
wrangler pages deploy dist
```
This command will prompt you to create a new project if one doesn't exist, and then deploy your dist folder to Cloudflare Pages.
Configure your project (optional): If you need more control over your deployment, you can create a wrangler.toml file in your project root:
```
name = "my-react-app"
compatibility_date = "2024-07-16" # Replace with the current date

[site]
bucket = "./dist"
```
Note: The account_id and workers_dev fields are typically not needed for Cloudflare Pages deployments.
Custom domain and production settings: To use a custom domain or configure production settings, you can use the Cloudflare Pages dashboard. There, you can set up your domain, configure environment variables, and manage other deployment settings.

Available npm Scripts

When working with the project directly (not using the npx command), you can use these npm scripts:

Script	Description
`npm run dev`	Start development server
`npm run build`	Build multi-file artifact (separate JS/CSS files)
`npm run build:single`	Build single-file artifact (inlined assets)
`npm run build:strict`	Build multi-file with TypeScript strict checking
`npm run build:single:strict`	Build single-file with TypeScript strict checking
`npm run preview`	Preview built artifacts locally
`npm run lint`	Run ESLint

Build Types

Multi-file builds (build, build:strict): Create separate HTML, JS, and CSS files in the dist/ directory
Single-file builds (build:single, build:single:strict): Create a single self-contained HTML file with all assets inlined
Strict builds (build:strict, build:single:strict): Include TypeScript type checking before building
Regular builds (build, build:single): Skip TypeScript checking for faster builds

Troubleshooting

If you encounter any issues, try the following:

Clear your browser cache and restart the development server.
Delete the node_modules folder and run npm install again.
Make sure your Node.js version is compatible with the project requirements.
Check for any error messages in the console and search for solutions online.

If problems persist, please open an issue on this project's GitHub repository.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Acknowledgements

Thanks to IntranetFactory for contributing the routing solution for handling multiple Artifacts.

Name		Name	Last commit message	Last commit date
Latest commit History 63 Commits
.github/workflows		.github/workflows
bin		bin
npx		npx
public		public
src		src
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
LICENSE		LICENSE
README.default.md		README.default.md
README.md		README.md
components.json		components.json
index.html		index.html
jsconfig.json		jsconfig.json
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.mjs		tailwind.config.mjs
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts
vite.single.config.ts		vite.single.config.ts

Uh oh!

License

Uh oh!

claudio-silva/claude-artifact-runner

Folders and files

Latest commit

History

Repository files navigation

Claude Artifact Runner

Table of Contents

What are Artifacts and why this project?

Use Cases

Quick Start

If you want to just run an Artifact

If you want to build an Artifact

If you want to view a previously built Artifact

If you want to create a full project for one or more Artifacts

Limitations

What's included?

Prerequisites

Installation

Command Syntax

Subcommands

Basic Usage

Run Artifact (Default)

Build Artifact

View Built Artifact

Create Project

Options by Subcommand

Run Subcommand Options

Build Subcommand Options

Create Subcommand Options

Global Options

All Command Line Options

Execution Workflow

run Subcommand (default)

build Subcommand

view Subcommand

create Subcommand

Subcommand Flow Matrix

Deployment Directory Logic (for build subcommand)

Notes

Alternative Methods of Installation

Using GitHub CLI

Create from a GitHub Template

Fork and Clone (Not Recommended)

After installation

Installing a single Artifact

Creating a multi-page application

Developing a more complex application

Customization

Removing unneeded components / libraries

Unneeded Shadcn UI components:

Unneeded packages (ex: Recharts):

Project structure

Building for production

Single file deployment

Building with strict checking

Multi-file deployment

Why would you want to do build this way, instead of building a single file?

Multi-file deployment with strict checking

Deploying your application

Local test deployment

Traditional web hosting

Cloud hosting platforms

Netlify

Vercel

GitHub Pages

Cloudflare Pages

Available npm Scripts

Build Types

Troubleshooting

Contributing

License

Acknowledgements

About

Topics

Resources

License

Uh oh!

`run` Subcommand (default)

`build` Subcommand

`view` Subcommand

`create` Subcommand

Deployment Directory Logic (for `build` subcommand)

Packages