Web Development Best Practices

Relevant source files

• Same.dev/Prompt.txt

This document describes Same.dev's standardized practices for web application development, including framework selection, tooling preferences, design standards, and deployment workflows. These guidelines ensure that generated applications are production-ready, browser-compatible, and optimized for Same.dev's cloud-based IDE environment.

For information about code editing and validation workflows in Same.dev, see Code Editing and Validation Workflow. For design system implementation details, see Design Standards and shadcn/ui Integration.

Framework and Package Manager Selection

Same.dev enforces specific tooling choices to optimize compatibility with its Docker-based Ubuntu 22.04 LTS environment located at /home/project.

Package Manager: Bun

Mandatory: Use bun over npm for all package management operations. When the startup tool is used, bun is automatically installed. Similarly, use bunx over npx for package execution.

Rationale: Bun provides faster installation and execution times in the Same.dev environment.

Sources: Same.dev/Prompt.txt79 Same.dev/Prompt.txt244

Framework Preferences

Framework	Use Case	Configuration Requirement
React with Vite	Single-page applications, component-heavy UIs	"dev": "vite --host 0.0.0.0" in package.json
Next.js	Server-side rendering, full-stack applications	"dev": "next dev -H 0.0.0.0" in package.json

Critical: The --host 0.0.0.0 flag (or -H 0.0.0.0 for Next.js) is mandatory to expose the development server to the user through Same.dev's iframe preview system. This configuration is automatically applied when using the startup tool but must be manually added when initializing projects via terminal commands.

Sources: Same.dev/Prompt.txt78-80 Same.dev/Prompt.txt245

Project Initialization Workflow

Sources: Same.dev/Prompt.txt78-80 Same.dev/Prompt.txt243-245 Same.dev/Prompt.txt52-60

Web API and Browser Compatibility Requirements

All web applications must be compatible with loading in an iframe and work across all major browsers. This constraint affects API selection.

Compatibility Substitutions

Prohibited API	Required Alternative	Reason
crypto.randomUUID()	Math.random()	crypto.randomUUID() is restricted in iframe context

Example: When generating unique identifiers, use:

Sources: Same.dev/Prompt.txt86 Same.dev/Prompt.txt251

Design System with shadcn/ui

Same.dev mandates the use of shadcn/ui for component libraries but requires extensive customization to prevent generic-looking applications.

shadcn/ui Integration

Installation Command: bunx shadcn@latest add -y -o

Note: The shadcn CLI has changed; this is the correct command format.

Component Customization Mandate

CRITICAL REQUIREMENT: Never use default shadcn/ui components. All components must be customized before building the main application to create unique designs.

Component Directory Structure

Components are installed to components/ui/ directory with filenames following the pattern:

• button.tsx
• input.tsx
• card.tsx
• dropdown.tsx
• dialog.tsx
• popover.tsx
• tooltip.tsx
• alert.tsx
• avatar.tsx
• badge.tsx
• breadcrumb.tsx
• calendar.tsx
• checkbox.tsx
• collapsible.tsx
• combobox.tsx
• command.tsx
• context-menu.tsx
• date-picker.tsx
• dropdown-menu.tsx
• form.tsx
• hover-card.tsx
• label.tsx
• menubar.tsx
• navigation-menu.tsx
• progress.tsx
• radio-group.tsx
• scroll-area.tsx
• select.tsx
• separator.tsx
• sheet.tsx
• skeleton.tsx
• slider.tsx
• switch.tsx
• table.tsx
• tabs.tsx
• textarea.tsx
• toast.tsx
• toggle.tsx
• use-dialog.tsx
• use-toast.tsx

Strategy: Edit each of these files individually to create visual distinctiveness.

Sources: Same.dev/Prompt.txt99-100 Same.dev/Prompt.txt264-265

Design Constraints

Rule	Requirement
Emojis	NEVER use in web applications
Default Colors	Avoid purple, indigo, blue unless specified in prompt
Image Colors	Use color palette from attached images when provided
Responsive Design	MUST generate responsive designs

Sources: Same.dev/Prompt.txt101-103 Same.dev/Prompt.txt266-268

3D Graphics with Three.js

Same.dev enforces the use of Vanilla Three.js over React Three Fiber for 3D graphics.

Three.js Configuration

Required Setup:

• Package Version: [email protected] + @types/[email protected]
• Import Pattern: import { OrbitControls } from 'three/addons/controls/OrbitControls.js'

Prohibited: React Three Fiber

Rationale: Vanilla Three.js is a known working configuration in Same.dev's environment and provides better compatibility.

Sources: Same.dev/Prompt.txt81 Same.dev/Prompt.txt246

Asset Management and Image Handling

Same.dev provides multiple pathways for image acquisition and integration.

Image Sources

1. web_search tool: Search for and find images
2. curl: Download images directly from URLs
3. Unsplash and high-quality sources: Preferred for stock photography
4. User uploads: Users can upload custom images to the project

Preference: Use URL links for images directly in the project rather than downloading and storing files locally.

Documentation Handling

When users provide documentation URLs, use the web_scrape tool to read the page content before proceeding with implementation.

Sources: Same.dev/Prompt.txt83-85 Same.dev/Prompt.txt248-250

Development Server and Preview Workflow

Same.dev provides a live preview system where users see their web application in an iframe on the right side of the screen.

Server Management Strategy

Workflow Principles

• Start Early: Launch the development server at the beginning of the project to enable runtime error detection
• Restart Before Versioning: Always restart the dev server before creating a new version
• Version Frequently: Create versions after every significant edit
• Interactive Feedback: Request user interaction to verify behavior that cannot be confirmed from screenshots alone
• Suggestions Tool: End the development cycle by proposing next version changes using the suggestions tool

Sources: Same.dev/Prompt.txt88-95 Same.dev/Prompt.txt253-260

Deployment and Production Configuration

Same.dev automatically deploys projects after each version, defaulting to static site deployment.

Deployment Workflow

Custom Domain Connection

Users who want to connect custom domains should:

1. Open the "Deployed" panel on the top right of the screen
2. Click the "Claim Deployment" button
3. Connect the project to their Netlify account
4. Manage deployment settings from Netlify

Same.dev retains access to update the deployment even after users claim it.

Sources: Same.dev/Prompt.txt91-92 Same.dev/Prompt.txt256-257

Website Cloning Guidelines

Same.dev supports pixel-perfect website cloning with specific ethical and security constraints.

Prohibited Cloning Targets

Category	Prohibition	Reason
Ethical/Legal Content	NEVER clone sites with borderline ethical, legal, pornographic, or privacy concerns	Legal and moral compliance
Login Pages	NEVER clone login forms or authentication pages	Phishing prevention

If a site requires authentication, request that users provide a screenshot after they log in.

Cloning Workflow

Design Analysis Requirements

Before writing any code for website cloning:

1. Analyze the complete design system
2. Communicate a detailed plan to the user using a ````plan``` block
3. Reference specific details: fonts, colors, spacing, backgrounds, gradients
4. Break down the UI into logical sections and pages
5. Confirm scope if the page is long

Animation Recreation

The web_scrape tool does not capture animation information. When cloning sites with animations:

• Study the animations carefully from the live site
• Think deeply about the best approach to recreate them
• Match the timing, easing, and behavior as closely as possible

Asset Handling

Any URLs pointing to same-assets.com can be used directly in the project without downloading.

Fullstack Implementation

Attempt to implement all implied fullstack functionalities, not just the visual interface. This includes:

• Form submissions
• Data persistence
• User interactions
• Dynamic content loading

Sources: Same.dev/Prompt.txt116-127 Same.dev/Prompt.txt280-292

Development Workflow Summary

The complete Same.dev web development workflow follows this pattern:

Phase	Actions	Tools/Commands
Initialization	Create project, install dependencies, configure dev script	startup tool, manual initialization with bunx
Setup	Create .same/ folder, start dev server	Directory creation, server launch
Component Customization	Install and customize shadcn/ui components	bunx shadcn@latest add -y -o, file editing
Development	Implement features, test in live preview	Code editing, run_linter tool
Versioning	Restart server, create version, analyze screenshot	Dev server restart, versioning tool
Deployment	Verify configuration, auto-deploy	Read netlify.toml, automatic deployment
Iteration	Gather user feedback, propose improvements	User interaction, suggestions tool

This workflow emphasizes:

• Early server startup for runtime error detection
• Frequent versioning to track progress
• Automatic deployment for production readiness
• User feedback loops for iterative improvement
• Design quality through mandatory component customization

Sources: Same.dev/Prompt.txt78-95 Same.dev/Prompt.txt242-260