Figma Docker Init

Quick-start Docker setup for Figma Make-exported React/Vite/TypeScript projects. This CLI tool generates production-ready Docker configurations tailored for different project types and deployment scenarios.

📢 What's New in v2.0.0

v2.0.0 - Stable Release (October 26, 2025)

🎉 STABLE RELEASE: Production-ready Docker setup with zero warnings and optimal developer experience

Key Features:

• ✅ Zero Warning Installation: Clean output with no template or configuration warnings
• ✅ Per-Project Configuration: Each project gets its own .figma-docker/ directory
• ✅ Detached Mode by Default: Containers start in background, terminal returns immediately
• ✅ HTTP-Only Development: Simplified nginx configuration without SSL complexity
• ✅ Automatic .env Creation: No manual file copying required
• ✅ GitHub Codespaces Ready: Validated and tested in cloud development environments

Installation:

npx figma-docker-init basic

Quick Start:

# Navigate to your React/Vite project
cd your-project

# Initialize Docker configuration
npx figma-docker-init basic

# Start containers in background
cd .figma-docker && docker-compose up -d --build

# View logs if needed
docker-compose logs -f

What's Included:

• Modern Docker Compose configuration (no obsolete version field)
• Optimized nginx proxy with WebSocket support for Vite HMR
• Multi-stage Dockerfile with production builds
• Comprehensive documentation in DOCKER.md
• Environment variable template (.env.example)
• Health checks and monitoring endpoints

📋 Beta Testing History

v2.0.0-beta.9 - Clean Output (October 26, 2025)

🧹 CLEANUP: Removed all template warnings for cleaner installation

v2.0.0-beta.8 - Improved User Experience (October 26, 2025)

📝 UX IMPROVEMENT: Docker containers now run in detached mode by default

Fixed Issues:

• ✅ Terminal Returns to Prompt: Added -d flag to run containers in background
• ✅ Clearer Instructions: Users now get their terminal back after starting containers
• ✅ Log Viewing: Added instructions for viewing logs with docker-compose logs -f

Installation:

npx figma-docker-init@beta basic

What Changed:

• Updated docker-compose command from up --build to up -d --build
• Containers start in background (detached mode)
• Terminal returns to prompt immediately
• Added log viewing instructions for users who want to see output

v2.0.0-beta.7 - Nginx SSL Fix (October 26, 2025)

🔧 HOTFIX: Fixed nginx crash loop caused by missing SSL certificates (complete fix)

Fixed Issues:

• ✅ Removed SSL Configuration: Eliminated SSL/HTTPS from basic template nginx.conf
• ✅ Nginx Stability: nginx now starts successfully without SSL certificates
• ✅ Simplified Configuration: Reduced nginx.conf from 182 lines to 100 lines for development
• ✅ HTTP-Only Mode: Basic template now uses HTTP-only (perfect for local development)

Installation:

npx figma-docker-init@beta basic

What Changed:

• Completely rewrote nginx.conf removing all SSL/TLS configuration
• Removed SSL server block requiring /etc/ssl/certs/server.crt
• Removed HTTPS redirect logic from HTTP server block
• Both app-dev and nginx services now start successfully
• All users get working nginx out of the box

For Production SSL:

• Use the ui-heavy template which includes SSL setup instructions
• Or manually add SSL certificates and configuration as needed

v2.0.0-beta.6 - Nginx SSL Fix (October 26, 2025)

🔧 HOTFIX: Fixed nginx crash loop caused by missing SSL certificates

Fixed Issues:

• ✅ Removed SSL Configuration: Eliminated SSL/HTTPS from basic template nginx.conf
• ✅ Nginx Stability: nginx now starts successfully without SSL certificates
• ✅ Simplified Configuration: Reduced nginx.conf from 182 lines to 98 lines for development
• ✅ HTTP-Only Mode: Basic template now uses HTTP-only (perfect for local development)

Installation:

npx figma-docker-init@beta basic

What Changed:

• Removed SSL/TLS server block requiring /etc/ssl/certs/server.crt
• Removed HTTPS redirect logic from HTTP server block
• Simplified nginx.conf for HTTP-only development
• Both app-dev and nginx services now start successfully

For Production SSL:

• Use the ui-heavy template which includes SSL setup instructions
• Or manually add SSL certificates and configuration as needed

v2.0.0-beta.5 - Documentation Fix (October 26, 2025)

📝 DOCUMENTATION: Fixed docker-compose instructions

Fixed Issues:

• ✅ Clearer Instructions: Updated docker-compose command to include cd to .figma-docker directory
• ✅ User Confusion: Removed "no configuration file provided" error by clarifying directory navigation

Installation:

npx figma-docker-init@beta basic

What Changed:

• Updated "Next Steps" to show: cd .figma-docker && docker-compose up --build
• Clarified that Docker files are in the .figma-docker/ subdirectory

v2.0.0-beta.4 - Critical Installation Fix (October 26, 2025)

🔧 HOTFIX: Resolves npm installation loop caused by unnecessary dependency

Fixed Issues:

• ✅ Removed AgentDB Dependency: Eliminated unnecessary 100+ MB ML dependency causing installation hangs
• ✅ Faster Installation: Reduced install time from minutes to seconds
• ✅ Node v16 Compatibility: Now works on older Node versions (though >=20.8.1 still recommended)
• ✅ Smaller Package Size: Reduced from 148KB to minimal size

Installation:

npx figma-docker-init@beta basic

What Changed:

• Removed agentdb dependency that was not used by the CLI tool
• Eliminated onnxruntime-node and other ML package downloads
• Fixed infinite loop during npm install on some systems

v2.0.0-beta.3 - Enhanced Developer Experience (October 26, 2025)

🎯 IMPROVEMENTS: Streamlined setup workflow and simplified Docker configuration

New Features:

• ✅ Automatic .env Creation: No longer need to manually copy .env.example to .env
• ✅ Simplified Docker Compose: Reduced from 267 lines to 78 lines for better maintainability
• ✅ Fixed YAML Syntax: Resolved context path issues and removed problematic template variables
• ✅ Improved Volume Paths: Changed build context to use parent directory correctly

Installation:

npx figma-docker-init@beta basic

What Changed:

• The setup script now automatically creates .env from .env.example
• Simplified docker-compose.yml template focuses on essential services
• Fixed build context paths to properly reference project files
• Removed complex monitoring services for cleaner initial setup

v2.0.0-beta.2 - Critical Bug Fixes (October 26, 2025)

🔧 HOTFIX: Resolves execution errors in v2.0.0-beta.1

Fixed Issues:

• ✅ Module System Compatibility: Converted CommonJS modules to ES modules for proper import/export
• ✅ Missing Dependencies: Added ensureFigmaDockerStructure function that was causing runtime errors
• ✅ Template Path Resolution: Fixed template discovery to correctly locate package templates
• ✅ GitHub Codespaces Support: Now works correctly in all npx environments

Installation:

npx figma-docker-init@beta basic

Recommended for: All users experiencing "SyntaxError" or "not defined" errors with beta.1

v2.0.0 - Per-Project Installation Architecture (October 2025)

• Per-Project Installation: Docker configurations now install to .figma-docker/ directory in each project
• Improved Path Resolution: Enhanced path handling for multi-project workflows
• Better Organization: Centralized configuration management per project
• Migration Support: Seamless migration from global to per-project setup
• 100% Test Coverage: All 368 tests passing across Ubuntu, Windows, and macOS
• Enhanced Error Handling: Better validation and user feedback

🚀 Features

• Per-Project Configuration: Each project gets its own .figma-docker/ directory
• Multiple Templates: Choose from optimized configurations for different project types
• Production Ready: Includes Nginx configuration, multi-stage builds, and security best practices
• Zero Config: Works out of the box with sensible defaults
• Customizable: Easy to modify generated files for specific needs
• TypeScript Support: Full TypeScript support with optimized builds
• Development Friendly: Hot reload support and development configurations

📦 Installation

Global Installation (Recommended)

npm install -g figma-docker-init

One-time Use (npx)

npx figma-docker-init [template]

Local Installation

npm install --save-dev figma-docker-init

🎯 Quick Start

1. Navigate to your React/Vite/TypeScript project root
2. Run the CLI tool:

figma-docker-init ui-heavy

3. Customize the generated .env.example file and rename it to .env
4. Build and run your containerized application:

docker-compose up --build

🛠️ Usage

Basic Command

figma-docker-init [template] [options]

Available Templates

basic

Minimal Docker setup with essential configuration:

• Basic Dockerfile with Node.js
• Simple docker-compose.yml
• Basic Nginx configuration
• Environment file template

figma-docker-init basic

ui-heavy

Optimized for UI-heavy applications with advanced caching and performance optimizations:

• Multi-stage Dockerfile with build optimization
• Advanced Nginx configuration with gzip and caching
• Performance-optimized docker-compose setup
• Comprehensive environment configuration

figma-docker-init ui-heavy

Command Options

# Show help information
figma-docker-init --help
figma-docker-init -h

# Show version
figma-docker-init --version
figma-docker-init -v

# List all available templates
figma-docker-init --list

📁 Generated Files

The CLI generates the following files in your project's .figma-docker/ directory:

your-project/
├── .figma-docker/          # Per-project Docker configuration
│   ├── config.json         # Project-specific settings
│   ├── Dockerfile          # Multi-stage build configuration
│   ├── docker-compose.yml  # Container orchestration
│   ├── .dockerignore       # Files to exclude from build context
│   ├── nginx.conf          # Nginx server configuration
│   ├── .env.example        # Environment variables template
│   └── DOCKER.md           # Detailed documentation
├── package.json            # Updated with Docker scripts
└── [your project files]

Directory Structure Benefits

• Isolation: Each project maintains its own Docker configuration
• Portability: Easy to version control and share
• Organization: Centralized configuration management
• Multi-Project: Support for multiple projects with different configurations

File Descriptions

• Dockerfile: Optimized multi-stage build with development and production targets
• docker-compose.yml: Complete orchestration with service definitions, networks, and volumes
• .dockerignore: Excludes unnecessary files from build context for faster builds
• nginx.conf: Production-ready Nginx configuration with security headers and caching
• .env.example: Template for environment variables with documentation
• DOCKER.md: Comprehensive guide for Docker usage and customization

🔧 Configuration

Environment Variables

Copy .env.example to .env and customize:

cp .env.example .env

Key variables to configure:

# Application
NODE_ENV=production
REACT_APP_API_URL=https://api.yourdomain.com

# Container Configuration
CONTAINER_PORT=3000
HOST_PORT=80

# Build Configuration
BUILD_TARGET=production

Customizing Templates

The generated files serve as a starting point. Common customizations include:

1. Dockerfile: Adjust Node.js version, add build steps, or install additional dependencies
2. nginx.conf: Modify server configuration, add SSL, or configure reverse proxy
3. docker-compose.yml: Add databases, Redis, or other services

🐳 Docker Commands

Development

# Build and start development environment
docker-compose up --build

# Start with logs
docker-compose up --build --logs

# Background mode
docker-compose up -d --build

Production

# Build production image
docker build --target production -t your-app:latest .

# Run production container
docker run -p 80:80 --env-file .env your-app:latest

# Using docker-compose for production
docker-compose -f docker-compose.yml up -d

Maintenance

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Remove volumes (careful!)
docker-compose down -v

# Rebuild without cache
docker-compose build --no-cache

🔒 Security Features

The generated configurations include security best practices:

• Non-root user: Containers run as non-root user
• Security headers: Nginx configured with security headers
• Minimal attack surface: Multi-stage builds exclude development dependencies
• Environment isolation: Proper environment variable handling
• Network security: Internal networking with docker-compose

🚀 Deployment

Cloud Platforms

The generated Docker configuration works with major cloud platforms:

• Vercel: Use Dockerfile for containerized deployments
• Heroku: Compatible with Heroku Container Registry
• AWS ECS/Fargate: Production-ready for AWS container services
• Google Cloud Run: Optimized for serverless containers
• DigitalOcean App Platform: Ready for platform deployment

CI/CD Integration

Example GitHub Actions workflow:

name: Build and Deploy
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build Docker image
        run: docker build -t app:latest .
      - name: Deploy to production
        run: # Your deployment commands

🛠️ Development

Prerequisites

• Node.js >= 20.8.1
• npm >= 10.0.0
• Docker >= 20.0.0
• Docker Compose >= 2.0.0

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test thoroughly
4. Commit with conventional commits: git commit -m "feat: add new template"
5. Push and create a Pull Request

Adding New Templates

1. Create a new directory in templates/
2. Add template files (Dockerfile, docker-compose.yml, etc.)
3. Update the CLI to recognize the new template
4. Add documentation and examples

📚 Examples

Basic React App

# In your React project
figma-docker-init basic
docker-compose up --build
# App available at http://localhost

Complex UI Application

# For apps with heavy UI components
figma-docker-init ui-heavy
cp .env.example .env
# Edit .env with your configuration
docker-compose up --build

Production Deployment

# Build production image
docker build --target production -t myapp:v1.0.0 .

# Tag for registry
docker tag myapp:v1.0.0 registry.com/myapp:v1.0.0

# Push to registry
docker push registry.com/myapp:v1.0.0

🐛 Troubleshooting

Common Issues

Build fails with permission errors:

# Fix permissions
sudo chown -R $USER:$USER .

Port already in use:

# Change port in docker-compose.yml
ports:
  - "8080:80"  # Use different host port

Out of disk space:

# Clean up Docker
docker system prune -a

Module not found errors:

# Rebuild without cache
docker-compose build --no-cache

📄 License

MIT License - see LICENSE file for details.

🤝 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🙏 Acknowledgments

• Inspired by create-react-app and similar bootstrapping tools
• Built for the Figma developer community
• Optimized for modern React/Vite/TypeScript workflows

Made with ❤️ for the Figma developer community