@dscodotco/theme-cli/docs/core-concepts.md

A CLI tool for developing Shopify themes

# Core Concepts

This guide explains the fundamental concepts of Theme CLI and how they work together to provide a powerful theme development environment.

## Theme Structure

### Overview

A Shopify theme is organized into several key directories:

```
theme/
├── assets/       # Static files (CSS, JS, images)
├── config/       # Theme settings and configuration
├── layout/       # Theme layout templates
├── sections/     # Reusable content sections
├── snippets/     # Reusable template snippets
└── templates/    # Page templates
```

### Templates

Templates are the foundation of your theme's pages. They can be:

- **Static**: Fixed pages like home, about, contact
- **Dynamic**: Generated pages for products, collections, blog posts

```liquid
{% comment %} templates/product.liquid {% endcomment %}
{% section 'product-template' %}
```

### Sections

Sections are modular, customizable components:

```liquid
{% comment %} sections/product-template.liquid {% endcomment %}
<div class="product">
  <h1>{{ product.title }}</h1>
  {% render 'product-price' %}
</div>
```

### Snippets

Snippets are reusable code fragments:

```liquid
{% comment %} snippets/product-price.liquid {% endcomment %}
<div class="price">
  {{ product.price | money }}
</div>
```

## Development Server

### Architecture

The development server provides:

1. **Live Preview**: Real-time updates as you edit files
2. **Asset Pipeline**: Compilation and optimization
3. **API Endpoints**: Theme metadata and rendering
4. **Hot Reload**: Instant browser updates

### Template Rendering

The server uses Shopify's API to render templates:

1. Template file is read
2. Content is uploaded as a temporary asset
3. Rendered HTML is fetched
4. Temporary asset is cleaned up

```typescript
const html = await renderer.renderTemplate('product', {
  product: {
    title: 'Example Product',
    price: 1999
  }
});
```

### Asset Pipeline

Assets are processed through configurable pipelines:

```typescript
server.configureAssets({
  compile: true,
  minify: true,
  sourcemaps: true
});
```

## Theme API

### Metadata

The Theme API provides detailed information about your theme:

```typescript
const metadata = await themeAPI.getMetadata();
// {
//   sections: ['header', 'footer', ...],
//   templates: {
//     'index': { type: 'static', ... },
//     'product': { type: 'dynamic', ... }
//   }
// }
```

### Page Management

Pages are managed through a consistent interface:

```typescript
const pages = await themeAPI.getPages();
// [
//   { path: '/', template: 'index', type: 'static' },
//   { path: '/products/*', template: 'product', type: 'dynamic' }
// ]
```

### Template Analysis

Analyze template dependencies and structure:

```typescript
const deps = await themeAPI.getTemplateDependencies('product');
// {
//   sections: ['header', 'product-template', 'footer'],
//   snippets: ['product-price', 'product-form']
// }
```

## Authentication

### API Access

Theme CLI requires Shopify API access:

1. **Admin API**: For theme management
2. **Storefront API**: For preview and rendering

Required scopes:
- `read_themes`
- `write_themes`
- `read_products`
- `read_content`

### Credentials

Credentials are managed through environment variables:

```env
SHOPIFY_STORE_NAME=your-store.myshopify.com
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_PASSWORD=your_api_password
SHOPIFY_THEME_ID=123456789
```

## Development Workflow

### Local Development

1. Start development server
2. Edit theme files
3. View changes in real-time
4. Test across devices

### Theme Deployment

1. Build production assets
2. Validate theme structure
3. Upload to Shopify
4. Update settings

```bash
# Development
theme-cli dev

# Production build
theme-cli build

# Deploy
theme-cli deploy
```

## Best Practices

### Theme Organization

1. **Modular Structure**
   - Break down into sections
   - Use snippets for reusable code
   - Keep templates focused

2. **Asset Management**
   - Use semantic naming
   - Optimize images
   - Minify production assets

3. **Version Control**
   - Use Git
   - Ignore sensitive files
   - Document changes

### Performance

1. **Asset Optimization**
   - Minimize HTTP requests
   - Use appropriate image formats
   - Enable compression

2. **Caching**
   - Implement browser caching
   - Use asset versioning
   - Cache API responses

3. **Code Quality**
   - Follow Liquid best practices
   - Minimize JavaScript
   - Optimize CSS

### Security

1. **API Security**
   - Secure credentials
   - Use environment variables
   - Implement rate limiting

2. **Development Server**
   - Use HTTPS in production
   - Validate user input
   - Implement CORS policies

## Advanced Features

### Custom Middleware

Add custom functionality to the development server:

```typescript
server.use(async (ctx, next) => {
  // Custom logic
  await next();
});
```

### Asset Processors

Add custom asset processors:

```typescript
server.addAssetProcessor('.scss', async (content, filepath) => {
  // Process SCSS files
  return compiledCSS;
});
```

### Event Handling

Listen for server events:

```typescript
server.on('fileChange', (path) => {
  // Handle file changes
});

server.on('compile', (asset) => {
  // Handle asset compilation
});
```

## Next Steps

- Explore the [API Reference](./api/README.md)
- Try the [Tutorials](./tutorials/README.md)
- Read about [Contributing](./development/contributing.md)
- Check [Best Practices](./development/best-practices.md)