@dscodotco/theme-cli/README.md

A CLI tool for developing Shopify themes

# @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](https://webcontainers.io).

[![npm version](https://img.shields.io/npm/v/@dscodotco/theme-cli.svg)](https://www.npmjs.com/package/@dscodotco/theme-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## 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:

```bash
npm install -g @dscodotco/theme-cli
```

## Usage

### Initialize a new Shopify theme

```bash
# 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:

```bash
# 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:

```typescript
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

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/theme-cli.git
   cd theme-cli
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the project:
   ```bash
   npm run build
   ```

4. Run locally:
   ```bash
   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](https://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](https://dsco.co)

---

Made with ❤️ by [DSCO](https://dsco.co)

# 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

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

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

## Quick Start

1. Create a `.env` file with your Shopify credentials:
```bash
# 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
```

2. Initialize a new theme:
```bash
theme-cli shopify theme init --name my-theme
```

3. Start the development server:
```bash
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:

```bash
# 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:

1. **Access Token (Recommended)**
   - Create a custom app in your Shopify admin
   - Generate an Admin API access token
   - Use the token as `SHOPIFY_PASSWORD`

2. **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

1. Clone the repository
2. Install dependencies: `npm install`
3. Run setup: `npm run setup`
4. 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