SimpleShop

A beautiful, customisable e-commerce storefront built with Phoenix LiveView. Designed for print-on-demand sellers who want professional shops without design expertise.

Features

The Shop

A complete storefront with all the pages you need:

• Home - Hero banner, category navigation, featured products, testimonials
• Products - Grid layout with hover effects and filtering
• Product Detail - Image gallery, variants, reviews, related products
• Cart - Full shopping cart with order summary
• Checkout - Stripe-hosted checkout with order confirmation
• About - Rich content with your brand story
• Contact - Contact form with business details
• Error pages - Themed 404/500 pages

Theme Editor (/admin/theme)

Customise your shop's look without touching code:

• 8 curated presets - Gallery, Studio, Boutique, Bold, Playful, Minimal, Night, Classic
• Real-time preview - See changes instantly across all page types
• Comprehensive customisation:
  • Mood (Neutral, Warm, Cool, Dark)
  • Typography (Clean, Editorial, Modern, Classic, Friendly, Minimal)
  • Shape (Sharp, Soft, Round, Pill)
  • Density (Compact, Balanced, Spacious)
  • Accent colours with automatic contrast
  • Layout options (grid columns, header style, width)
  • Feature toggles (announcement bar, sticky header, etc.)
• Logo upload with optional SVG recolouring
• Header image with zoom and position controls

Technical Highlights

• CSS custom properties for instant theme switching
• Three-layer CSS architecture (primitives → attributes → semantic)
• ETS-based CSS caching for performance
• SQLite database with BLOB storage for images
• Shared PageTemplates between preview and live shop

Getting Started

Prerequisites

• Elixir 1.17+
• Erlang 27+
• Node.js 20+ (for assets)

Setup

# Clone the repository
git clone <repo-url>
cd simpleshop_theme

# Install dependencies
mix setup

# Start the server
mix phx.server

Visit:

• Shop: http://localhost:4000
• Theme Editor: http://localhost:4000/admin/theme

Running Tests

mix test

Project Structure

lib/
├── simpleshop_theme/           # Core business logic
│   ├── settings.ex             # Theme settings context
│   ├── settings/
│   │   └── theme_settings.ex   # Theme settings schema
│   ├── media.ex                # Image upload handling
│   └── theme/
│       ├── css_generator.ex    # Generates CSS from settings
│       ├── css_cache.ex        # ETS cache for generated CSS
│       ├── presets.ex          # 8 theme presets
│       └── preview_data.ex     # Mock data for previews
│
├── simpleshop_theme_web/       # Web layer
│   ├── components/
│   │   ├── layouts/            # App and shop layouts
│   │   ├── page_templates/     # Shared page templates (*.heex)
│   │   ├── page_templates.ex   # PageTemplates module
│   │   └── shop_components.ex  # Reusable shop UI components
│   ├── live/
│   │   ├── theme_live/         # Theme editor LiveView
│   │   └── shop_live/          # Public shop LiveViews
│   └── controllers/
│       └── error_html.ex       # Themed error pages

assets/css/
├── app.css                     # Main stylesheet
├── theme-layer1-primitives.css # Design tokens
├── theme-layer2-attributes.css # Theme-specific values
└── theme-layer3-semantic.css   # Component styles

Routes

Path	Description
/	Shop home page
/collections/all	All products
/collections/:slug	Category collection (filterable)
/products/:id	Product detail page
/cart	Shopping cart
/checkout	Create Stripe session (POST)
/checkout/success	Order confirmation
/webhooks/stripe	Stripe webhook endpoint
/about	About page
/contact	Contact page
/admin/theme	Theme editor (requires auth)
/dev/errors/404	Preview 404 page (dev only)
/dev/errors/500	Preview 500 page (dev only)

Stripe Checkout

SimpleShop uses Stripe Checkout (hosted payment page) for secure payment processing.

Setup

1. Create a Stripe account
2. Get your API keys from the Stripe Dashboard
3. Set environment variables:

export STRIPE_SECRET_KEY="sk_test_..."
export STRIPE_WEBHOOK_SECRET="whsec_..."

Local webhook testing

Use the Stripe CLI to forward webhooks to your local server:

stripe listen --forward-to localhost:4000/webhooks/stripe

The CLI will print a webhook signing secret — use that as STRIPE_WEBHOOK_SECRET.

Test cards

Number	Result
4242 4242 4242 4242	Successful payment
4000 0000 0000 0002	Declined
4000 0025 0000 3155	Requires 3D Secure

Use any future expiry date and any 3-digit CVC.

Generating Mockups

The project includes a Printify integration for generating product mockups. This is useful for creating sample product images from Unsplash artwork.

Prerequisites

1. A Printify account with API access
2. Set the PRINTIFY_API_TOKEN environment variable

Usage

# Generate all mockups (saves to priv/static/mockups/)
export PRINTIFY_API_TOKEN="your-token"
mix generate_mockups

# Generate mockups and delete products from Printify afterwards
mix generate_mockups --cleanup

# Search for available blueprints
mix generate_mockups --search "poster"

# List all blueprints
mix generate_mockups --list-blueprints

Product definitions are in lib/simpleshop_theme/printify/mockup_generator.ex.

Documentation

• ROADMAP.md - Future features and improvements
• docs/plans/ - Feature plans
• docs/research/ - Design research and guidelines

Design Philosophy

1. "One theme, infinite variations" - Rather than multiple themes, one solid foundation with curated customisation
2. Constrained creativity - Limit choices to prevent poor design outcomes
3. No professional photography required - Works with product mockups
4. Mobile-first - All features work on touch devices
5. Ethical design - No dark patterns or fake urgency

License

AGPL-3.0