@dscodotco/theme-cli v1.0.14
@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