Artifacts Builder

Stack: React 18 + TypeScript + Vite + Tailwind CSS + shadcn/ui

Workflow

1. Initialize: bash scripts/init-artifact.sh <project-name>
2. Develop in generated project
3. Bundle: pnpm run build (Vite bundling, see Step 3 for configuration)
4. Share bundled HTML with user
5. Test only if needed (optional)

Artifact Types

Type 1: Complex Interactive Applications

Multi-component applications with state management and routing. Use React stack above.

Type 2: Interactive Primary Source Artifacts

Explorable visualizations of documentation, papers, books. Use HTML with collapsibles and structured navigation (no React).

Reference: primary-sources-reference.md

Use for: Technical docs, research papers, books/textbooks, historical documents

Design Guidelines

Avoid "AI slop": no excessive centered layouts, purple gradients, uniform rounded corners, or Inter font.

Step 1: Initialize

bash scripts/init-artifact.sh <project-name>

Location: ~/Desktop/Artifacts/ (fallback: current directory)

Creates:

• React + TypeScript (Vite)
• Tailwind CSS 3.4.1 + shadcn/ui theming
• Path aliases (@/)
• 40+ shadcn/ui components + Radix UI dependencies
• Parcel configured (.parcelrc)
• Node 18+ compatibility

Step 2: Develop

cd ~/Desktop/Artifacts/<project-name>

Edit generated files. See Common Development Tasks for guidance.

Step 3: Bundle

bash scripts/bundle-artifact.sh

Requirement: index.html in project root

Output: bundle.html - self-contained artifact with inlined JavaScript, CSS, dependencies

Process:

• Installs: parcel, @parcel/config-default, parcel-resolver-tspaths, html-inline
• Creates .parcelrc with path alias support
• Builds with Parcel (no source maps)
• Inlines all assets

Fallback: Vite + vite-plugin-singlefile

If Parcel fails (e.g., @swc/core signature errors on macOS), use Vite:

1. Install vite-plugin-singlefile:

   pnpm add -D vite-plugin-singlefile
   

2. Update vite.config.ts with complete configuration:

   import { viteSingleFile } from "vite-plugin-singlefile";
   
   export default defineConfig({
     plugins: [react(), viteSingleFile()],
     resolve: {
       alias: {
         "@": path.resolve(__dirname, "./src"),
       },
     },
     build: {
       rollupOptions: {
         output: {
           inlineDynamicImports: true,
           manualChunks: undefined,
         },
       },
       cssCodeSplit: false,
     },
   });
   

3. Build:

   pnpm run build
   

4. Output: dist/index.html - fully self-contained, opens directly in browser (file:// protocol)

Critical: The build configuration is required. Without inlineDynamicImports: true, manualChunks: undefined, and cssCodeSplit: false, the bundle will not work properly (JavaScript won't execute, modules won't load).

When to use:

• Parcel bundling fails with signature errors
• Custom inline scripts produce non-executable output
• Need reliable single-file distribution

Step 4: Share

Share bundle.html (or dist/index.html if using Vite fallback) in conversation for user to view as artifact.

Step 5: Testing (Optional)

Test only if requested or issues arise. Use available tools (Playwright, Puppeteer). Avoid upfront testing—adds latency.

Reference

• shadcn/ui components: https://ui.shadcn.com/docs/components