Web Dev Experiments

A personal playground for exploring UI interactions, shaders, and modern web development techniques.

You can find my experiments here.

Purpose

The goal of this project is to provide a robust environment for rapid prototyping. It allows for the exploration of new ideas, libraries, and techniques without the overhead of setting up a new project every time, while ensuring that each experiment remains strictly isolated from others.

Prerequisites

• Node.js: v20 or higher
• npm: v10 or higher

Project Structure

The project is organized to separate the main application dashboard from the isolated experiments.

experiments/
├── public/
│   └── experiments/          # Experiment assets (images, models)
├── src/
│   ├── app/
│   │   ├── (main)/           # Dashboard application routes
│   │   └── experiments/      # Isolated experiment routes
│   │       └── (group)/      # Route groups (opt-out of main layout)
│   ├── components/
│   │   ├── ui/               # Shared dashboard components (Shadcn)
│   │   └── experiments/      # Experiment-specific components
│   └── lib/                  # Shared utilities
├── scripts/                  # Automation scripts (cleanup, etc.)
└── plopfile.js               # Scaffolding generator

Architecture

To ensure that experiments do not interfere with each other or the main application layout:

• Isolated Environments: Each experiment runs in its own route group.
• Style Isolation: The main application uses global styles (Tailwind, Shadcn), but experiments can opt-out or use their own isolated CSS to ensure a clean slate.
• Component Independence: Components are built specifically for their experiment, often developed in isolation using Storybook before integration.

Technology Stack

• Framework: Next.js 16 (App Router)
• Styling: Tailwind CSS & Shadcn UI (Main Dashboard)
• Animation: Framer Motion
• 3D Graphics: React Three Fiber / Three.js
• Tooling: Plop.js for scaffolding, Vitest for testing, Storybook for component development.

Workflow & Automation

We use custom automation to streamline the creative process and maintain project cleanliness.

1. Scaffold a New Experiment (plop.js)

Instead of manually creating folders and files, we use a CLI generator to scaffold new experiments.

npm run new:experiment

This command:

• Prompts for an experiment name and description.
• Generates the route structure in src/app/experiments.
• Creates a dedicated component directory in src/components/experiments.
• Creates a metadata file (experiment.json) which allows the dashboard to automatically list the experiment.
• Creates an asset directory in public/experiments/<name> for images/models.
• Sets up initial Storybook stories.

2. Develop Components (Storybook)

Complex interactions are best built in isolation.

npm run storybook

We use Storybook to build and refine components without the noise of the full application context.

3. Integration

Once components are ready, they are assembled into the page file designated for that experiment.

4. Verification

Visit http://localhost:3000/experiments/<experiment-name> to see your creation live.

5. Cleanup

Experiments can be transient. If an idea doesn't work out or is no longer needed, it can be cleanly removed.

npm run delete:experiment <experiment-name>

This script removes all associated files (routes, components, public assets). Because the registry is dynamic, the experiment automatically disappears from the dashboard.

Best Practices

• Strict Isolation: Do not import components from other experiments. Keep dependencies self-contained.
• No Global Store Pollution: Avoid adding experiment-specific state to global stores unless absolutely necessary.
• Cleanups: Use useEffect cleanups for event listeners, timers, or WebGL contexts to prevent memory leaks when navigating away.

AI-Assisted Development

This project includes rules and workflows for AI coding assistants (like Antigravity, Cursor, GitHub Copilot Chat) that help maintain the isolation architecture automatically.

Available Workflows

Command	Purpose
/new-experiment	Scaffold a new experiment with all required files
/develop-experiment	Work on an existing experiment with isolation guardrails
/cleanup-experiment	Safely remove an experiment and all its files
/add-experiment-component	Add a new component within an experiment
/add-experiment-assets	Add images, 3D models, or other assets

What the AI Knows

The .agent/ directory contains:

• Rules that enforce isolation (no cross-experiment imports, correct file locations)
• Workflows with code templates for common patterns (Framer Motion, React Three Fiber, etc.)

This means AI assistants will automatically:

• Use npm run new:experiment instead of manually creating files
• Place components in the correct experiment directory
• Follow cleanup patterns for useEffect hooks
• Avoid modifying shared code for experiment-specific needs

Getting Started

1. Install dependencies:

   npm install

2. Run the development server:

   npm run dev

   Visit http://localhost:3000 for the main dashboard.

3. Run component workbench (Storybook):

   npm run storybook

4. Run tests:

   npm run test

License

MIT