132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
---
|
|
name: Building Artifacts
|
|
description: Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Artifacts are automatically saved to ~/Desktop/Artifacts directory. Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
|
|
license: Complete terms in LICENSE.txt
|
|
---
|
|
|
|
# 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
|
|
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
|
|
|
|
```bash
|
|
cd ~/Desktop/Artifacts/<project-name>
|
|
```
|
|
|
|
Edit generated files. See **Common Development Tasks** for guidance.
|
|
|
|
## Step 3: Bundle
|
|
|
|
```bash
|
|
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**:
|
|
```bash
|
|
pnpm add -D vite-plugin-singlefile
|
|
```
|
|
|
|
2. **Update vite.config.ts** with complete configuration:
|
|
```typescript
|
|
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**:
|
|
```bash
|
|
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
|