@dscodotco/theme-cli

@dscodotco/theme-cli

A command-line interface for working with e-commerce themes, starting with Shopify themes. This tool is designed to work in browser environments like webcontainers.io.

Features

• ✨ Initialize a new Shopify theme based on Dawn (without requiring Git)
• 🌐 Works in browser environments like webcontainers.io
• 📦 Designed to be run with npx without global installation
• 🚀 Extensible architecture for adding support for more platforms
• 🚀 Start a development server for Shopify themes with real-time rendering

Installation

This package is designed to be used with npx without installation, but you can install it globally if you prefer:

npm install -g @dscodotco/theme-cli

Usage

Initialize a new Shopify theme

# Using npx (recommended)
npx @dscodotco/theme-cli shopify theme init

# Or with a custom name
npx @dscodotco/theme-cli shopify theme init --name my-custom-theme

# Specify an output directory
npx @dscodotco/theme-cli shopify theme init --output-dir /path/to/projects

# Force overwrite if directory exists
npx @dscodotco/theme-cli shopify theme init --force

# If installed globally
theme-cli shopify theme init

Options for theme initialization

• --name, -n: Specify a custom name for the theme directory (default: "my-theme")
• --force, -f: Overwrite the directory if it already exists
• --output-dir, -o: Directory where the theme will be created (defaults to current directory)

Start a development server

Run a local development server that renders Shopify Liquid templates using Shopify's own rendering engine:

# Using npx
npx @dscodotco/theme-cli shopify theme dev \
  --store your-store \
  --api-key your-api-key \
  --password your-admin-api-password \
  --theme-id 123456789

# Specify theme directory and port
npx @dscodotco/theme-cli shopify theme dev \
  --store your-store \
  --api-key your-api-key \
  --password your-admin-api-password \
  --theme-id 123456789 \
  --theme-dir ./my-theme \
  --port 4000

Options for development server

• --store, -s: Your Shopify store name without .myshopify.com (required)
• --api-key, -k: Your Shopify Admin API key (required)
• --password, -p: Your Shopify Admin API password/token (required)
• --theme-id, -t: ID of the theme to use for development (required)
• --theme-dir, -d: Theme directory path (defaults to current directory)
• --port: Port for the preview server (defaults to 3000)

Programmatic Usage

You can also use the package programmatically in your JavaScript/TypeScript projects:

import { initShopifyTheme } from '@dscodotco/theme-cli';

// Initialize a theme with custom options
await initShopifyTheme({ 
  name: 'my-store-theme',
  outputDir: './projects',
  force: true
});

Development

Prerequisites

• Node.js 18 or later
• npm, yarn, or pnpm

Setting up the Development Environment

• Clone the repository:

  git clone https://github.com/yourusername/theme-cli.git
  cd theme-cli
  

• Install dependencies:

  npm install
  

• Build the project:

  npm run build
  

• Run locally:

  npm start -- shopify theme init
  

Project Structure

theme-cli/
├── src/                  # Source code
│   ├── commands/         # Command implementations
│   │   └── shopify/      # Shopify specific commands
│   ├── utils/            # Utility functions
│   └── types/            # TypeScript type definitions
├── dist/                 # Compiled output
└── ...

Webcontainer Compatibility

This tool is specifically designed to work in webcontainers.io environments. It downloads theme files directly from URLs rather than using Git, making it ideal for browser-based development environments.

License

MIT © dsco.co

Made with ❤️ by DSCO

Shopify Theme CLI

A command-line interface for working with Shopify themes, featuring a local development server with live preview capabilities.

Features

• Initialize new Shopify themes based on Dawn
• Start a development server with live preview
• Render Liquid templates using Shopify's engine
• Browse and preview theme files locally
• Automatic theme creation for development

Installation

# Install globally
npm install -g @dscodotco/theme-cli

# Or use with npx
npx @dscodotco/theme-cli

Quick Start

• Create a .env file with your Shopify credentials:

# Store information
SHOPIFY_STORE=your-store-name    # Without .myshopify.com

# Authentication (choose one option)
# Option 1: Access token (recommended)
SHOPIFY_PASSWORD=shpat_...       # Admin API access token

# Option 2: API key and secret
SHOPIFY_API_KEY=...              # Admin API key
SHOPIFY_PASSWORD=...             # Admin API secret

# Optional
SHOPIFY_THEME_ID=...            # Existing theme ID

• Initialize a new theme:

theme-cli shopify theme init --name my-theme

• Start the development server:

theme-cli shopify theme dev --store your-store --api-key your-key --password your-password

Development Scripts

We provide several scripts to help with development:

# Initial project setup
npm run setup

# Local development (without npm publish)
npm run theme:dev

# Development using published package
npm run theme:dev:npm

# Clean build artifacts and theme files
npm run clean

Project Structure

├── src/                  # Source code
│   ├── cli.ts           # CLI implementation
│   ├── index.ts         # Entry point
│   └── utils/           # Utility functions
├── scripts/             # Development scripts
│   ├── local-theme-dev.sh    # Local development
│   ├── project-setup.sh      # Project setup
│   └── setup-theme-dev.sh    # Published package setup
└── dist/                # Compiled code

Authentication

The CLI supports two authentication methods:

• Access Token (Recommended)

  • Create a custom app in your Shopify admin
  • Generate an Admin API access token
  • Use the token as SHOPIFY_PASSWORD

• API Key and Secret

  • Create a private app in your Shopify admin
  • Use the API key and secret/password

Required API scopes:

• read_themes
• write_themes

Development Server

The development server provides:

• File explorer for theme files
• Live preview of templates
• Automatic theme creation
• Real-time Liquid rendering

Access the development interface at http://localhost:3000 when running the server.

Contributing

• Clone the repository
• Install dependencies: npm install
• Run setup: npm run setup
• Start development: npm run theme:dev

Security

• Never commit your .env file
• Keep your API credentials secure
• Use access tokens instead of API keys when possible
• Regularly rotate your credentials

License

MIT License - see LICENSE.md for details