Claude Artifact Runner

Warning: currently the project is compatible with Node.js up to v22.
It breaks under the latest Node.js v23.
This issue will be fixed.
For the time being, I recommend that you use Node.js v22.11 with npm 10.9.

Table of Contents

• Summary
• Overview
• Project scope
• What's included?
• Prerequisites
• Getting started
• Project structure
• Usage
• Customization
• Building for production
• Deploying your application
  • Local test deployment
  • Traditional web hosting
  • Cloud hosting platforms
    • Netlify
    • Vercel
    • GitHub Pages
    • Cloudflare Pages
• Troubleshooting
• Contributing
• License
• Acknowledgements

Summary

If you're searching for a way to take the small web applications Claude generates with its Artifacts feature, and run them outside of its website, you've come to the right place.

This project provides a standalone environment that mimics the Artifacts runtime, enabling you to run, test, and further develop the code generated by Claude independently from its website.

Overview

If you've created a web application or component using Claude's Artifacts feature and want to:

1. run the component locally for testing and development,
2. use the component as a starting point for a new project or integrate it into a larger project, or
3. deploy the component as a standalone application,

you'll be disappointed to find out that, if you download the artifact code via the download button, you'll only receive a single file containing the main logic of the app, not the full project with all necessary files to run it on your computer.

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 Artifact running as easily and as soon as possible.

This scaffold/boilerplate provides the fastest and easiest way to get your artifact up and running on your machine. It includes all the necessary dependencies and configurations to seamlessly transition your Claude-generated artifact into a fully functional web application in no time.

Project scope

This project is meant only 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.

Why? Well, because those types of simple static content are easily viewable by other means.
For example, to view Mermaid diagrams, you can use an online viewer/editor, like mermaidflow.app, from which you can also export the diagram to SVG or PNG.

What's included?

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

1. React 18 for building user interfaces.
2. TypeScript to support artifacts written in type-safe Javascript.
3. Vite for fast development and building.
4. Shadcn UI for pre-built, customizable components.
5. Tailwind CSS for compact and expressive embedded styling.
6. Recharts for creating dynamic, customizable charts and data visualizations.
7. 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.
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 (version 14 or later)
• npm (usually comes with Node.js)

Getting started

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Start the development server:

   npm run dev
   

4. Open your browser and visit http://localhost:5173 to see the default app running.

Project structure

• src/: Contains the source code for the application
  • App.tsx: Main application component
  • artifact-component.tsx: Place to paste the component generated by Claude
  • components/: Reusable UI components
  • lib/: Utility functions and helpers
• public/: Static assets
• index.html: Entry HTML file
• vite.config.ts: Vite configuration
• tsconfig.json: TypeScript configuration
• tailwind.config.js: Tailwind CSS configuration
• package.json: all the required packages are registered here.

Usage

1. Generate a React component using Claude on the Artifacts environment.
2. Copy the generated component code.
3. Paste the code into src/artifact-component.tsx, completely replacing the file contents.
4. If you have npm run dev running, the page should refresh automatically to display the new component.

Customization

• Use src/index.css to add additional CSS rules.
• Place static assets (such as images) in the public folder.
• Modify tailwind.config.js to customize the Tailwind CSS theme.
• Update App.tsx to change the overall layout or add new features.
• Add or modify components in the src/components/ directory.

  Note: Shadcn UI components installed via npx are automatically placed in src/components. 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 folder from src/components.

Unneeded packages (ex: Recharts):

Use npm remove to uninstall them.

Building for production

To create a production build, run:

npm run build

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

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 use the serve package:

1. Install serve globally:

   npm install -g serve
   

2. Navigate to your project directory and run:

   serve -s dist
   

3. 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:

1. 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

1. Install the Netlify CLI:

   npm install -g netlify-cli
   

2. Run the following command in your project directory:

   netlify deploy
   

3. Follow the prompts. When asked for the publish directory, enter dist.

4. For production deployment, use:

   netlify deploy --prod
   

Vercel

1. Install the Vercel CLI:

   npm install -g vercel
   

2. Run the following command in your project directory:

   vercel
   

3. Follow the prompts. Vercel will automatically detect that it's a Vite project and use the correct settings.

GitHub Pages

1. If you haven't already, create a GitHub repository for your project.

2. Install the gh-pages package:

   npm install gh-pages --save-dev
   

3. Add these scripts to your package.json:

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

4. Run:

   npm run deploy
   

5. 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:

1. Install Wrangler:

   npm install -g wrangler
   

2. Login to Cloudflare:

   wrangler login
   

3. 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.

4. 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.

5. 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.

Troubleshooting

If you encounter any issues, try the following:

1. Clear your browser cache and restart the development server.
2. Delete the node_modules folder and run npm install again.
3. Make sure your Node.js version is compatible with the project requirements.
4. 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

I found Claude-React-Jumpstart when looking for a way to run Artifacts outside of claude.ai.

However, it did not fully meet my needs, so I decided to make my own project, as I wanted something that:

• was completely pre-configured (no need to install or configure additional stuff),
• was ready to go with a single npm install, and
• included all components and libraries needed to fully replicate the Artifacts environment.