basker-theme-dev

A CLI tool for local development of static website themes with S3 sync.

Features

• Real-time File Syncing - Watch local directory for file changes and sync to S3
• Local Development Server - Serve files locally with Hono server
• Hybrid Content Serving - Prioritize local files over S3 content
• Remote Proxy - Access remote tenant site for files not available locally
• Authentication Support - Secure proxy integration with Payload CMS
• Multi-tenant Themes - Support for tenant and theme-specific development
• Response Caching - Local caching for improved performance
• Quick Preview - See local changes before they're synced to S3
• Developer Experience - Enhanced terminal output with status messages
• Error Resilience - Retry logic with exponential backoff for API failures
• Performance Optimized - Efficient handling of large directories

Installation

# Install globally
npm install -g basker-theme-dev

# Using yarn
yarn global add basker-theme-dev

# Using pnpm
pnpm add -g basker-theme-dev

# Or use with npx
npx basker-theme-dev

Quick Start

# Initialize configuration file
basker config init

# Start the development server
basker theme dev

Usage

# Display help
basker --help

# Start the development server
basker theme dev --bucket my-s3-bucket 

# Specify port and directory
basker theme dev --bucket my-s3-bucket --port 8080 --directory ./theme

# Initialize a configuration file
basker config init

Configuration

Create a basker-theme.json file in your project root:

{
  "bucket": "my-s3-bucket",
  "port": 3000,
  "directory": "./theme",
  "awsRegion": "eu-west-1",
  "debounceDelay": 300,
  "tenantSlug": "example-tenant",
  "themeKey": "example-theme",
  "themeId": "677f79ceedfc09859d0e4cd1",
  "proxyUrl": "https://api.example.com/proxy",
  "ignorePatterns": [
    "node_modules/**",
    ".git/**"
  ],
  "contentType": {
    ".html": "text/html",
    ".css": "text/css"
  },
  "cacheControl": "public, max-age=3600"
}

Configuration Options

| Option | Description | Default | |--------|-------------|---------| | bucket | S3 bucket name to sync with | Required | | port | Local development server port | 3000 | | directory | Local directory to watch | ./ | | awsRegion | AWS region for S3 bucket | eu-west-1 | | debounceDelay | Milliseconds to wait before syncing after changes | 300 | | ignorePatterns | Glob patterns for files to ignore | [] | | tenantSlug | Tenant identifier for multi-tenant setup | "" | | themeKey | Theme identifier within tenant | "" | | themeId | Database ID of the theme (defaults to hardcoded value) | "677f79ceedfc09859d0e4cd1" | | proxyUrl | URL for proxy service integration | "" | | contentType | Custom content type mappings | {} | | cacheControl | Cache-Control header for S3 objects | "" |

AWS Credentials

Basker uses AWS SDK's default credential provider chain:

1. Environment variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
2. AWS profile in ~/.aws/credentials
3. EC2 instance profile or ECS task role (if running on AWS infrastructure)

Command Reference

basker theme dev

Start the development server and file watcher.

basker theme dev [options]

| Option | Description | |--------|-------------| | --bucket, -b | S3 bucket name | | --port, -p | Server port | | --directory, -d | Local directory to watch | | --region, -r | AWS region | | --config, -c | Path to config file | | --tenant, -t | Tenant slug | | --theme, -k | Theme key | | --proxy-url | URL for proxy service |

basker config init

Initialize a new configuration file.

basker config init [options]

| Option | Description | |--------|-------------| | --force, -f | Overwrite existing config file |

basker auth login

Authenticate with the proxy service.

basker auth login [options]

| Option | Description | |--------|-------------| | --email, -e | Email for authentication | | --tenant, -t | Tenant slug |

basker auth status

Check authentication status.

basker auth status

basker auth logout

Log out from the proxy service.

basker auth logout

Examples

Basic Usage

# Start server with default settings
basker theme dev --bucket my-bucket

Custom Setup

# Start server with custom settings
basker theme dev --bucket my-bucket --port 8080 --directory ./src

Using Configuration File

# Create a config file
basker config init

# Start using config file
basker theme dev

Multi-tenant Theme Development

# Login to the proxy service
basker auth login --email [email protected] --tenant my-tenant

# Start development with tenant and theme options
basker theme dev --bucket my-bucket --tenant my-tenant --theme my-theme --proxy-url https://api.example.com/proxy

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development

# Clone the repository
git clone https://github.com/your-username/basker-theme-dev.git
cd basker-theme-dev

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode with watch
pnpm dev

# Run tests
pnpm test

Troubleshooting

Common Issues

1. AWS Authentication Errors: Ensure AWS credentials are correctly configured
2. Permission Denied: Verify S3 bucket permissions
3. Port Already in Use: Change port using --port option
4. Slow Syncing: Adjust debounceDelay in config or exclude large files
5. Proxy Authentication Failed: Check your login credentials with basker auth status and try logging in again
6. Tenant/Theme Not Found: Verify your tenant slug and theme key are correct
7. Proxy Connection Failed: Check your network connection and the proxy URL
8. Invalid Theme Path: Ensure theme key format follows the required pattern

License

MIT © Basker Team