PureMix Framework

https://github.com/tacho87/puremix
Admin
PureMix is an HTML-first server-side rendering framework that seamlessly integrates JavaScript,...
Tokens:165,762
Snippets:631
Trust Score:7
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install PureMix Project

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

Creates a new PureMix project using npx. This is the recommended way to start a new PureMix application.

```bash
npx puremix create my-app
```

--------------------------------

### Test Puremix Installation and Development Server

Source: https://github.com/tacho87/puremix/blob/main/TODO.md

Installs the Puremix package globally, creates a new project using a basic template, installs dependencies, and starts the development server. It verifies the installed version and checks if the application runs correctly in the browser. This process helps ensure a smooth setup for new users.

```bash
# Create test directory
mkdir ../puremix-test-install
cd ../puremix-test-install

# Install your published package
npm install -g puremix@alpha

# Test CLI commands
puremix --version
# Should show: 0.1.0-alpha.1

# Create test project
puremix create test-app --template basic

# Test development server
cd test-app
npm install
npm run dev

# Open browser: http://localhost:3000
# ✅ Should see working PureMix app!

# Clean up
cd ../..
rm -rf puremix-test-install
```

--------------------------------

### Run PureMix Development Server

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

Installs project dependencies and starts the development server for a PureMix application. The app will be available at http://localhost:3000.

```bash
cd my-app
npm install
npm run dev
```

--------------------------------

### Install and Run PureMix Development Server

Source: https://github.com/tacho87/puremix/blob/main/templates/default/README.md

Installs project dependencies using npm and starts the development server. This command is essential for local development and testing.

```bash
# Install dependencies
npm install

# Start development server
npm run dev
```

--------------------------------

### Install and Run PureMix Minimal Template

Source: https://github.com/tacho87/puremix/blob/main/templates/minimal/README.md

Commands to create a new PureMix project using the minimal template, install dependencies, start the development server, and access the application.

```bash
# Create a new project
npx puremix create my-app --template minimal
cd my-app

# Install dependencies (minimal!)
npm install

# Start development server
npm run dev

# Visit your app
open http://localhost:3000
```

--------------------------------

### Install PureMix Globally

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

Installs PureMix globally on your system, allowing you to use the 'puremix' command from any directory.

```bash
npm install -g puremix
```

--------------------------------

### JavaScript API Documentation and Endpoints

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Defines API endpoints for product management using JavaScript. This example demonstrates how to structure API responses and define request parameters for GET and POST methods.

```javascript
export default async function handler(request, response) {
  return response.status(200).json({
    version: '1.0',
    endpoints: {
      products: {
        list: {
          method: 'GET',
          path: '/api/products',
          description: 'Get list of products',
          query: {
            page: 'Page number (default: 1)',
            limit: 'Items per page (default: 20)',
            sort: 'Sort field and order (e.g., price:desc)',
            inStock: 'Filter by stock status (true/false)'
          },
          response: {
            success: true,
            data: [],
            pagination: {}
          }
        },
        get: {
          method: 'GET',
          path: '/api/products/:id',
          description: 'Get single product',
          response: {
            success: true,
            data: {}
          }
        },
        create: {
          method: 'POST',
          path: '/api/products',
          description: 'Create new product',
          body: {
            name: 'Product name (required)',
            price: 'Product price (required)',
            description: 'Product description',
            inStock: 'Stock status (default: true)'
          },
          response: {
            success: true,
            data: {},
            message: 'Product created successfully'
          }
        }
      }
    }
  });
}
```

--------------------------------

### Complete Client Example with User Profile Loading

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

Demonstrates a full client-side example using PureMix. This involves loading user data and settings via a loader, displaying them in the UI, and handling updates through server calls. It showcases how to access loader data and interact with server functions from the client.

```html
<loader>
      async function loadUserProfile(request) {
        const user = await getUser(request.params.id);
        const settings = await getSettings(user.id);
    
        return {
          data: { user, settings }
        };
      }
    </loader>
    
    <div>
      <h1 id="user-name">{loadUserProfile.data.user.name}</h1>
      <button onclick="handleUpdate()">Update Name</button>
    </div>
    
    <script>
      // Client-side JavaScript
      document.addEventListener('DOMContentLoaded', function() {
        // Access loader data
        const user = PureMix.data.loadUserProfile.data.user;
        console.log('Loaded user:', user.name);
    
        // Apply theme from settings
        const theme = PureMix.data.loadUserProfile.data.settings.theme;
        if (theme === 'dark') {
          document.body.classList.add('dark-theme');
        }
      });
    
      async function handleUpdate() {
        const result = await PureMix.call('updateUserName', {
          userId: PureMix.data.loadUserProfile.data.user.id,
          name: 'New Name'
        });
    
        if (result.success) {
          // Update UI
          document.getElementById('user-name').textContent = result.user.name;
        }
      }
    </script>
    
    <script server>
      async function updateUserName(data, request) {
        const user = await updateUser(data.userId, {
          name: data.name
        });
    
        return { success: true, user };
      }
    </script>
```

--------------------------------

### Vite + React: Build Tool Configuration

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Configuration for using Vite with React, including installation commands and the vite.config.js setup. Specifies output directory and entry point for production builds. Designed for production applications with frameworks.

```bash
npm install vite @vitejs/plugin-react
```

```javascript
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    outDir: 'public/dist',
    rollupOptions: {
      input: './src/main.js'
    }
  }
});
```

```html
<script type="module" src="/dist/main.js"></script>
```

--------------------------------

### Dockerfile for PureMix Production Deployment

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

A Dockerfile setup for deploying a PureMix application. It includes installing Node.js, Python (optional), dependencies, copying application code, exposing ports, and defining a health check.

```dockerfile
FROM node:22-alpine

# Install Python (optional, for Python features)
RUN apk add --no-cache python3 py3-pip

WORKDIR /app

# Install Python packages (if using Python features)
COPY requirements.txt* ./
RUN if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

# Install Node dependencies
COPY package*.json ./
RUN npm ci --production

# Copy application code
COPY . .

EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"

# Run production server
CMD ["puremix", "start", "--host", "0.0.0.0"]
```

--------------------------------

### Products API

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

An example of a simple API route that returns a JSON response.

```APIDOC
## GET /api/products

### Description
This endpoint serves a list of products with basic API information.

### Method
GET

### Endpoint
/api/products

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the API.
- **version** (string) - The version of the API.

#### Response Example
```json
{
  "success": true,
  "message": "Products API",
  "version": "1.0"
}
```
```

--------------------------------

### PureMix File-Based Routing Examples

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Illustrates how PureMix automatically generates routes based on file structure, including static, nested, dynamic parameters, and catch-all routes.

```bash
# Static routes
app/routes/index.puremix              → /
app/routes/about.puremix              → /about
app/routes/contact.puremix            → /contact

# Nested routes
app/routes/products/index.puremix     → /products
app/routes/products/new.puremix       → /products/new

# Dynamic parameters
app/routes/users/[id].puremix         → /users/:id
app/routes/blog/[category]/[slug].puremix → /blog/:category/:slug

# Catch-all routes
app/routes/docs/[...path].puremix     → /docs/*
```

--------------------------------

### Configuration Validation Error Example (JavaScript)

Source: https://github.com/tacho87/puremix/blob/main/docs/CONFIGURATION.md

Illustrates an example of an invalid PureMix configuration and the corresponding startup error message. This highlights how PureMix validates configuration values on startup, providing specific feedback for incorrect types or missing required fields, such as `port` or `session.secret`.

```javascript
// Invalid configuration example
export default {
  port: 'invalid-port',  // Will show error: Port must be a number
  session: {
    // Missing required 'secret' field
  }
};

// Startup error:
// ❌ Invalid configuration:
//    - port: must be a number, got string
//    - session.secret: required field missing

```

--------------------------------

### Project Structure Example

Source: https://github.com/tacho87/puremix/blob/main/tests/projects/comprehensive-test/FRAMEWORK_GUIDE.md

Illustrates a typical project directory structure for a PureMix application. It outlines the placement of routes, components, layouts, services, static assets, and the configuration file.

```tree
your-project/
├── app/
│   ├── routes/          # File-based routing
│   │   ├── index.puremix       # /
│   │   ├── about.puremix       # /about
│   │   ├── [id].puremix        # /:id (dynamic)
│   │   └── api/                # API routes
│   ├── components/      # Reusable .puremix components
│   ├── layouts/         # Layout templates
│   └── services/        # Business logic (Python/JS/TS)
├── public/              # Static assets
└── puremix.config.js    # Framework configuration
```

--------------------------------

### PureMix Production Deployment Commands

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Provides command-line instructions for starting a PureMix application in production mode. It shows how to set environment variables like NODE_ENV and PORT.

```bash
# Direct production start
NODE_ENV=production puremix start --port 3000 --host 0.0.0.0

# With environment file
NODE_ENV=production PORT=8080 puremix start
```

--------------------------------

### Importing Components and Utilities in PureMix

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

Examples of how to import components and utilities within a PureMix project using ES module syntax. Demonstrates importing from local files within the project structure.

```javascript
// Import components
import Header from '../components/Header.puremix';
import UserCard from '../components/UserCard.puremix';

// Import utilities
import { db } from '../lib/database.js';
import { authenticate } from '../lib/auth.js';

// Import services
import { sendEmail } from '../services/email.js';
import { analyzeData } from '../services/analytics.py';

```

--------------------------------

### GET /api/products - List Resources

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Retrieves a list of products with support for pagination, filtering, and sorting.

```APIDOC
## GET /api/products

### Description

This endpoint retrieves a list of products from the database. It supports query parameters for pagination, filtering by stock status and minimum price, and sorting by specified fields.

### Method

```
GET
```

### Endpoint

```
/api/products
```

### Query Parameters

- **page** (integer) - Optional - The page number to retrieve (default: 1).
- **limit** (integer) - Optional - The number of items per page (default: 20).
- **inStock** (boolean) - Optional - Filter products by their stock status (e.g., `true`, `false`).
- **minPrice** (float) - Optional - Filter products with a price greater than or equal to this value.
- **sort** (string) - Optional - Sort products by a field and order, e.g., `price:desc` or `name:asc`.

### Request Example

```bash
# Basic request
GET /api/products

# With pagination
GET /api/products?page=2&limit=10

# With filtering
GET /api/products?inStock=true&minPrice=100

# With sorting
GET /api/products?sort=price:desc
```

### Response

#### Success Response (200)

- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - An array of product objects.
- **pagination** (object) - An object containing pagination details:
  - **page** (integer) - The current page number.
  - **limit** (integer) - The number of items per page.
  - **total** (integer) - The total number of products matching the filter.
  - **totalPages** (integer) - The total number of pages available.
  - **hasNext** (boolean) - Indicates if there is a next page.
  - **hasPrev** (boolean) - Indicates if there is a previous page.

#### Error Response (500)

- **success** (boolean) - Indicates if the request was successful.
- **error** (string) - An error message describing the issue.

#### Response Example (Success)

```json
{
  "success": true,
  "data": [
    {
      "_id": "60d5ecf1f1f1f1f1f1f1f1f1",
      "name": "Product A",
      "price": 19.99,
      "inStock": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}
```

#### Response Example (Error)

```json
{
  "success": false,
  "error": "Database connection failed"
}
```
```

--------------------------------

### Install PureMix Project with npm

Source: https://github.com/tacho87/puremix/blob/main/README.md

Use the npx command to create a new PureMix project with interactive template selection. This command initiates the project setup process, allowing you to choose from various templates.

```bash
npx puremix create my-app
cd my-app
npm install
npm run dev
```

--------------------------------

### SCSS Entry Point Example (SCSS)

Source: https://github.com/tacho87/puremix/blob/main/docs/CSS_BUILD_SYSTEM.md

An example of an SCSS entry point file (`styles.scss`) that utilizes Tailwind CSS directives (`@tailwind base`, `@tailwind components`, `@tailwind utilities`), imports custom mixins, and defines custom component styles using Tailwind's `@apply` directive.

```scss
// app/public/css/styles.scss
@tailwind base;
@tailwind components;
@tailwind utilities;

// Import custom mixins
@import './_mixins.scss';

// Custom styles
@layer components {
  .btn {
    @apply inline-flex items-center px-4 py-2 border rounded-md;
    
    &:hover {
      @apply bg-gray-50;
    }
  }
}
```

--------------------------------

### Bash Request Example for Python API

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

An example of how to make a POST request to the Python API endpoint using bash. This demonstrates the expected request format, including the Content-Type header and the JSON payload structure.

```bash
POST /api/data
Content-Type: application/json

{
  "data": [
    {"value": 10},
    {"value": 20},
    {"value": 30}
  ]
}

```

--------------------------------

### Install Testing Dependencies with npm

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Installs essential testing dependencies for PureMix applications using npm. Includes Jest for unit testing and Playwright for end-to-end testing.

```bash
# Install testing dependencies
npm install --save-dev jest @jest/globals supertest
npm install --save-dev @playwright/test  # For E2E testing
```

--------------------------------

### Install VSCE (Visual Studio Code Extension Tool) (Bash)

Source: https://github.com/tacho87/puremix/blob/main/plugins/PUBLISHING_GUIDE.md

Instructions for installing the VSCE tool, which is used for packaging and publishing VS Code extensions. It can be installed globally using npm or locally within a project directory.

```bash
# Install globally
npm install -g @vscode/vsce

# Or locally in project directory
cd plugins/vscode-puremix
npm install @vscode/vsce
```

--------------------------------

### Component Props Examples (.puremix)

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Illustrates various ways to pass props to components in .puremix files, including string, object, array, boolean, and mixed data types.

```html
<!-- String props -->
<UserCard name="John" role="admin" />

<!-- Object props -->
<UserCard user={loadPage.data.user} />

<!-- Array props -->
<ProductList items={loadPage.data.products} />

<!-- Boolean props -->
<Modal isOpen={true} />

<!-- Mixed props -->
<Dashboard
  user={loadPage.data.user}
  stats={loadPage.data.stats}
  isAdmin={true}
/>
```

--------------------------------

### Enable Nginx Configuration and Reload

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

These bash commands guide the process of enabling an Nginx site configuration, testing its syntax, and reloading the Nginx service to apply changes. It also includes a command to install an SSL certificate using Certbot.

```bash
# Enable site
sudo ln -s /etc/nginx/sites-available/puremix-app /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

# Install SSL certificate with Certbot
sudo certbot --nginx -d example.com -d www.example.com
```

--------------------------------

### Test Environment Setup with Jest Mocks

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Sets up the testing environment by configuring Node.js environment variables and mocking production dependencies using Jest. Includes global test utilities.

```javascript
// Configure test environment
process.env.NODE_ENV = 'test';
process.env.SESSION_SECRET = 'test-secret';

// Mock production dependencies jest.mock('./lib/puremix-engine');

// Global test utilities
global.createTestApp = require('./helpers/test-app');
global.mockRequest = require('./helpers/mock-request');
```

--------------------------------

### List Resources (GET) with Pagination, Filtering, and Sorting

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Handles GET requests to list resources, implementing pagination, filtering (inStock, minPrice), and sorting (field:order). It returns resource data along with pagination details or an error message. Requires database connection and Product model.

```javascript
import { connectDB, Product } from '../../lib/database.js';

export default async function handler(request, response) {
  // Only handle GET requests
  if (request.method !== 'GET') {
    return response.status(405).json({
      error: 'Method not allowed',
      allowed: ['GET']
    });
  }

  try {
    await connectDB();

    // Pagination
    const page = parseInt(request.query.page || '1');
    const limit = parseInt(request.query.limit || '20');
    const skip = (page - 1) * limit;

    // Filtering
    const filter = {};
    if (request.query.inStock) {
      filter.inStock = request.query.inStock === 'true';
    }
    if (request.query.minPrice) {
      filter.price = { $gte: parseFloat(request.query.minPrice) };
    }

    // Sorting
    const sort = {};
    if (request.query.sort) {
      const [field, order] = request.query.sort.split(':');
      sort[field] = order === 'desc' ? -1 : 1;
    }

    const products = await Product.find(filter)
      .sort(sort)
      .limit(limit)
      .skip(skip);

    const total = await Product.countDocuments(filter);

    return response.status(200).json({
      success: true,
      data: products,
      pagination: {
        page,
        limit,
        total,
        totalPages: Math.ceil(total / limit),
        hasNext: page * limit < total,
        hasPrev: page > 1
      }
    });
  } catch (error) {
    return response.status(500).json({
      success: false,
      error: error.message
    });
  }
}
```

--------------------------------

### Basic Production Start Command for PureMix

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

Commands to start a PureMix application in production mode. This can be done using npm or the PureMix CLI directly. It sets the NODE_ENV to production and allows specifying port and host.

```bash
# Set environment and start server
NODE_ENV=production npm start
```

```bash
NODE_ENV=production npx puremix start --port 3000 --host 0.0.0.0
```

--------------------------------

### CSS Autoprefixer Input and Output Example

Source: https://github.com/tacho87/puremix/blob/main/docs/CSS_BUILD_SYSTEM.md

Illustrates the function of Autoprefixer in ensuring browser compatibility by adding vendor prefixes. The example shows a CSS rule for `user-select: none;` as input and its transformed output with `-webkit-`, `-moz-`, and `-ms-` prefixes, ensuring wider browser support.

```css
/* Input */
.user-select-none {
  user-select: none;
}

/* Output */
.user-select-none {
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
}
```

--------------------------------

### Interactive CLI Commands

Source: https://github.com/tacho87/puremix/blob/main/README.md

Provides examples of using the PureMix interactive command-line interface (CLI) for project creation and management. The CLI offers guided prompts for template selection and feature descriptions.

```bash
# Enhanced project creation with template descriptions
./cli/puremix.ts create my-app

# Interactive prompts guide template selection
# Each template includes detailed feature descriptions
```

--------------------------------

### Basic PureMix Loader for Data Fetching

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

An example of a basic server-side loader in PureMix that fetches data (e.g., products) and can optionally display a message based on the result of a previous action.

```html
<loader>
  async function loadPage(request, actionResult) {
    // Fetch data from database, API, etc.
    const products = await getProducts();

    // Check if an action just ran
    const message = actionResult?.success
      ? 'Product saved successfully!'
      : null;

    return {
      data: { products, message }
    };
  }
</loader>
```

--------------------------------

### Creating New PureMix Projects with CLI

Source: https://github.com/tacho87/puremix/blob/main/CLAUDE.MD

Bash commands using the PureMix CLI (`./cli/puremix.ts`) to create new applications from different templates (basic, minimal, advanced), followed by installation and starting the development server.

```bash
# From framework root - All templates tested and working with MCP Playwright ✅
./cli/puremix.ts create my-app --template basic    # Modern Tailwind CSS + animations
./cli/puremix.ts create my-app --template minimal  # Clean responsive CSS, zero deps
./cli/puremix.ts create my-app --template advanced # Full MongoDB + auth + admin panel
cd my-app
npm install
npm run dev
```

--------------------------------

### Build and Start Production Server in PureMix

Source: https://github.com/tacho87/puremix/blob/main/templates/minimal/README.md

Commands to build the PureMix application for production and start the production server.

```bash
npm run build

NODE_ENV=production npm start
```

--------------------------------

### Separate Method Exports for API Endpoints (JavaScript)

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

This JavaScript example demonstrates defining separate exported functions for each HTTP method (GET, POST) in an API route. This approach provides clear separation of concerns for different operations on a resource, such as listing products (GET) and creating a new product (POST).

```javascript
// File: app/routes/api/products.js
export async function GET(request, response) {
  const products = await getProducts();
  return response.json({ data: products });
}

export async function POST(request, response) {
  const newProduct = await createProduct(request.body);
  return response.status(201).json({ data: newProduct });
}
```

--------------------------------

### Basic PM2 Process Management Commands

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

Essential commands for using PM2, a production process manager for Node.js applications. This includes installing PM2, starting an application, checking status, viewing logs, restarting, and stopping processes.

```bash
# Install PM2
npm install -g pm2

# Start application
pm2 start "puremix start" --name my-app

# Check status
pm2 status

# View logs
pm2 logs my-app

# Restart
pm2 restart my-app

# Stop
pm2 stop my-app
```

--------------------------------

### Products API

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Endpoints for retrieving, creating, and managing products.

```APIDOC
## GET /api/products

### Description
Get a list of products, with options for pagination, sorting, and filtering by stock status.

### Method
GET

### Endpoint
/api/products

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1)
- **limit** (integer) - Optional - Items per page (default: 20)
- **sort** (string) - Optional - Sort field and order (e.g., price:desc)
- **inStock** (boolean) - Optional - Filter by stock status (true/false)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - An array of product objects.
- **pagination** (object) - Pagination details.
```

```APIDOC
## GET /api/products/:id

### Description
Get a single product by its ID.

### Method
GET

### Endpoint
/api/products/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the product to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - The product object.
```

```APIDOC
## POST /api/products

### Description
Create a new product.

### Method
POST

### Endpoint
/api/products

### Parameters
#### Request Body
- **name** (string) - Required - Product name.
- **price** (number) - Required - Product price.
- **description** (string) - Optional - Product description.
- **inStock** (boolean) - Optional - Stock status (default: true).

### Request Example
{
  "name": "Example Product",
  "price": 99.99,
  "description": "A sample product",
  "inStock": true
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - The created product object.
- **message** (string) - Confirmation message.
```

--------------------------------

### Install VS Code PureMix Extension Locally

Source: https://github.com/tacho87/puremix/blob/main/PLUGIN_DEVELOPMENT.md

Steps to install the PureMix VS Code extension locally for development. This involves navigating to the extension directory, installing Node.js dependencies, packaging the extension using `vsce`, and then installing the generated `.vsix` file.

```bash
cd plugins/vscode-puremix/

# Install dependencies (if any)
npm install

# Package the extension
npm install -g vsce
vsce package

# This creates: puremix-0.1.0.vsix

# Install in VS Code
code --install-extension puremix-0.1.0.vsix
```

--------------------------------

### PureMix Route Creation Example

Source: https://github.com/tacho87/puremix/blob/main/templates/default/README.md

Demonstrates how to create a new route in a PureMix application by adding a .puremix file to the app/routes/ directory. Includes a loader function for data fetching and basic JSX for rendering.

```html
<!-- app/routes/about.puremix -->
<layout>main</layout>

<loader>
  async function loadPage(request) {
    return {
      data: { title: 'About Us' }
    };
  }
</loader>

<div>
  <h1>{loadPage.data.title}</h1>
  <p>Welcome to our about page!</p>
</div>
```

--------------------------------

### Separate Handlers for Each HTTP Method (JavaScript)

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

This example shows how to define separate exported functions for each HTTP method (GET, POST) in a JavaScript file. The framework automatically routes requests to the matching method handler, promoting cleaner organization for different operations. It assumes the existence of functions like getAllProducts and createProduct.

```javascript
// app/routes/api/products.js

export async function GET(request, response) {
  const products = await getAllProducts();
  return response.status(200).json({ success: true, data: products });
}

export async function POST(request, response) {
  const newProduct = await createProduct(request.body);
  return response.status(201).json({ success: true, data: newProduct });
}
```

--------------------------------

### Paginate Products and Render UI

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

This snippet demonstrates server-side pagination for fetching products and client-side rendering of the product list and navigation controls. It assumes a `Product` model and a database connection are available. The output includes product data, current page, total pages, and navigation state.

```html
<loader>
  async function loadPage(request) {
    const page = parseInt(request.query.page || '1');
    const limit = 20;

    await connectDB();
    const products = await Product.find()
      .limit(limit)
      .skip((page - 1) * limit);

    const total = await Product.countDocuments();

    return {
      data: {
        products,
        currentPage: page,
        totalPages: Math.ceil(total / limit),
        hasNext: page * limit < total,
        hasPrev: page > 1
      }
    };
  }
</loader>

<div>
  {loadPage.data.products.map(p => <div>{p.name}</div>)}

  <div class="pagination">
    {loadPage.data.hasPrev &&
      <a href="?page={loadPage.data.currentPage - 1}">Previous</a>
    }

    <span>Page {loadPage.data.currentPage} of {loadPage.data.totalPages}</span>

    {loadPage.data.hasNext &&
      <a href="?page={loadPage.data.currentPage + 1}">Next</a>
    }
  </div>
</div>
```

--------------------------------

### GET /api/users/:id/profile

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

This endpoint retrieves the profile of a specific user. It expects a GET request with the user ID in the path.

```APIDOC
## GET /api/users/:id/profile

### Description
Retrieves the profile of a specific user.

### Method
GET

### Endpoint
/api/users/:id/profile

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the user whose profile to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (object) - The user profile object.

#### Response Example
```json
{
  "data": {
    "userId": "user-123",
    "bio": "Software engineer and avid hiker.",
    "website": "https://example.com"
  }
}
```
```

--------------------------------

### GET /api/products/:id

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

This endpoint retrieves a specific product by its ID. It expects a GET request with the product ID in the path.

```APIDOC
## GET /api/products/:id

### Description
Retrieves a specific product by its ID.

### Method
GET

### Endpoint
/api/products/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the product to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (object) - The product object.

#### Response Example
```json
{
  "data": {
    "id": "abc-123",
    "name": "Existing Gadget",
    "price": 120.50
  }
}
```
```

--------------------------------

### GET /api/users

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

This endpoint retrieves a list of users. It expects a GET request and returns user data upon success.

```APIDOC
## GET /api/users

### Description
Retrieves a list of all users.

### Method
GET

### Endpoint
/api/users

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - An array of user objects.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "1",
      "name": "John Doe"
    },
    {
      "id": "2",
      "name": "Jane Smith"
    }
  ]
}
```
```

--------------------------------

### Test REST API Endpoints for Products (JavaScript)

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Tests the basic CRUD operations for the /api/products endpoint using the Supertest library. It verifies that GET requests return a list, POST requests create a product, PUT requests update a product, and DELETE requests remove a product. Assumes an Express.js application setup.

```javascript
// tests/api/rest-endpoints.test.js
describe('REST API Endpoints', () => {
  test('GET /api/products should return product list', async () => {
    const response = await request(app)
      .get('/api/products')
      .expect(200);

    expect(response.body).toHaveProperty('success', true);
    expect(response.body).toHaveProperty('data');
    expect(Array.isArray(response.body.data)).toBe(true);
  });

  test('POST /api/products should create new product', async () => {
    const newProduct = {
      name: 'Test Product',
      price: 29.99,
      description: 'A test product'
    };

    const response = await request(app)
      .post('/api/products')
      .send(newProduct)
      .expect(201);

    expect(response.body).toHaveProperty('success', true);
    expect(response.body.data).toHaveProperty('name', newProduct.name);
    expect(response.body.data).toHaveProperty('price', newProduct.price);
  });

  test('PUT /api/products/:id should update product', async () => {
    const updateData = {
      name: 'Updated Product',
      price: 39.99
    };

    const response = await request(app)
      .put('/api/products/123')
      .send(updateData)
      .expect(200);

    expect(response.body).toHaveProperty('success', true);
    expect(response.body.data).toHaveProperty('name', updateData.name);
  });

  test('DELETE /api/products/:id should delete product', async () => {
    const response = await request(app)
      .delete('/api/products/123')
      .expect(200);

    expect(response.body).toHaveProperty('success', true);
    expect(response.body).toHaveProperty('message', 'Product deleted successfully');
  });
});
```

--------------------------------

### URL Path API Versioning Example (Bash)

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Demonstrates file structure for URL path-based API versioning. Different versions of resources (e.g., users, products) are placed in separate versioned directories (v1, v2, v3) within the API routes. This is a recommended strategy for clear versioning.

```bash
# File structure for versioned APIs
app/routes/api/
├── v1/
│   ├── users.js          # GET /api/v1/users
│   └── products.js       # GET /api/v1/products
├── v2/
│   ├── users.js          # GET /api/v2/users (new fields)
│   └── products.js       # GET /api/v2/products (breaking changes)
└── v3/
    └── users.js          # GET /api/v3/users (major rewrite)
```

--------------------------------

### PureMix File Structure Example

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Demonstrates the main sections of a .puremix file: layout, head, imports, loader for server-side data fetching, HTML template, server-side JavaScript actions, server-side Python actions, and client-side scripts.

```html
<!-- 1. LAYOUT (optional) -->
<layout>main</layout>

<!-- 2. HEAD (optional - custom meta tags, scripts) -->
<head>
  <title>Page Title</title>
  <meta name="description" content="Page description">
</head>

<!-- 3. IMPORTS -->
<imports>
  import { getUser } from '../controllers/users'
  import { validate_email } from '../services/validators'
  import UserCard from '../components/UserCard.puremix'
</imports>

<!-- 4. LOADER (server-side data fetching) -->
<loader>
  async function loadPage(request, actionResult) {
    const userId = request.params.id;
    const user = await getUser(userId);

    return {
      data: { user },           // Required: data for template
      state: { isEditing: false } // Optional: UI state
    };
  }
</loader>

<!-- 5. HTML TEMPLATE -->
<div class="container">
  <h1>{loadPage.data.user.name}</h1>

  <!-- Component usage -->
  <UserCard user={loadPage.data.user} />

  <!-- Form with server action -->
  <form onsubmit="updateUser">
    <input name="name" value="{loadPage.data.user.name}">
    <button type="submit">Update</button>
  </form>
</div>

<!-- 6. SERVER SCRIPTS (JavaScript actions) -->
<script server>
  async function updateUser(formData, request) {
    const name = formData.get('name');
    const user = await saveUser(request.params.id, { name });
    return { success: true, user };
  }
</script>

<!-- 7. SERVER SCRIPTS (Python actions) -->
<script server lang="python">
def analyze_user(data, js_context=None):
    """Python function with pandas, numpy, etc."""
    import pandas as pd
    df = pd.DataFrame(data)
    return {'success': True, 'stats': df.describe().to_dict()}
</script>

<!-- Call Python function from form -->
<form onsubmit="analyze_user">
  <input type="hidden" name="userId" value="{loadPage.data.user.id}">
  <button type="submit">Analyze User Data</button>
</form>

<!-- 8. CLIENT SCRIPTS (browser-side) -->
<script>
  // Runs in the browser
  document.addEventListener('DOMContentLoaded', function() {
    // Access loader data
    const userData = PureMix.data.loadPage.data.user;
    console.log('User:', userData.name);
  });
</script>
```

--------------------------------

### Puremix Installation: Vue.js

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Install the Vue.js library to enable progressive enhancement and reactive data binding in your Puremix application. This command uses npm for package management.

```bash
npm install vue
```

--------------------------------

### Loader Function Example

Source: https://github.com/tacho87/puremix/blob/main/tests/projects/comprehensive-test/FRAMEWORK_GUIDE.md

Provides an example of a loader function within a .puremix file. Loaders are responsible for fetching data on the server before the page is rendered, taking `request` and `actionResult` as arguments and returning data.

```html
<loader>
  async function loadPage(request, actionResult) {
    const data = await fetchData();
    return { data };
  }
</loader>
```

--------------------------------

### Initialize and Start PureMix Framework Engine

Source: https://context7.com/tacho87/puremix/llms.txt

This snippet demonstrates how to initialize and start the main PureMix engine. It configures essential parameters like port, application directory, development mode, hot reloading, Python integration, and session management. The server is then started, and graceful shutdown is handled for SIGTERM and SIGINT signals.

```typescript
import PureMixEngine from 'puremix';

// Basic server setup
const engine = new PureMixEngine({
  port: 3000,
  appDir: 'app',
  isDev: true,
  hotReload: true,
  pythonTimeout: 30000,
  session: {
    secret: process.env.SESSION_SECRET || 'dev-secret-key',
    cookie: {
      maxAge: 24 * 60 * 60 * 1000, // 24 hours
      secure: process.env.NODE_ENV === 'production'
    }
  },
  python: {
    enabled: true,
    usePool: true,
    minWorkers: 2,
    maxWorkers: 8
  },
  verboseDebug: {
    enabled: true,
    level: 'debug',
    console: true,
    save: false
  }
});

// Start the server
await engine.start();
console.log('Server running on http://localhost:3000');

// Graceful shutdown
process.on('SIGTERM', () => engine.stop());
process.on('SIGINT', () => engine.stop());

```

--------------------------------

### Install SCSS/SASS Dependencies (Bash)

Source: https://github.com/tacho87/puremix/blob/main/docs/CSS_BUILD_SYSTEM.md

Installs Sass and postcss-scss, which are necessary for processing SCSS/SASS files within the PureMix build system. These packages enable the compilation of SCSS into standard CSS.

```bash
npm install -D sass postcss-scss
```

--------------------------------

### Install Dependencies for PureMix App

Source: https://github.com/tacho87/puremix/blob/main/templates/basic/README.md

Command to install all necessary project dependencies after creating a new PureMix application. This should be run in the root directory of the newly created project.

```bash
npm install
```

--------------------------------

### Start Production Server using PureMix CLI

Source: https://context7.com/tacho87/puremix/llms.txt

This command starts the production server for a PureMix application. It can be run directly using the `puremix start` command with specified port and environment variables, or by navigating to the build output directory and executing the `server.js` file.

```bash
# Direct production start
NODE_ENV=production puremix start --port 3000

# Using built production bundle
cd dist
node server.js

```

--------------------------------

### Install Tailwind CSS Dependencies (Bash)

Source: https://github.com/tacho87/puremix/blob/main/docs/CSS_BUILD_SYSTEM.md

Installs Tailwind CSS, along with its form and typography plugins, PostCSS, and Autoprefixer. These are essential for using Tailwind CSS within the PureMix project.

```bash
npm install -D tailwindcss @tailwindcss/forms @tailwindcss/typography postcss autoprefixer
```

--------------------------------

### Package and Install VS Code Extension Locally

Source: https://github.com/tacho87/puremix/blob/main/TODO.md

Installs the `vsce` tool, packages the VS Code extension into a `.vsix` file, and then installs this file locally into VS Code. This allows for testing the extension's functionality, such as syntax highlighting and auto-closing brackets, directly within the IDE.

```bash
cd plugins/vscode-puremix/

# Install vsce (VS Code packaging tool)
npm install -g vsce

# Package the extension
vsce package

# This creates: puremix-0.1.0.vsix

# Install in VS Code
code --install-extension puremix-0.1.0.vsix

# Test it:
# 1. Create a new file: test.puremix
# 2. Type "puremix-page" and press Tab
# 3. Verify syntax highlighting works
# 4. Verify auto-closing brackets work
```

--------------------------------

### Start PureMix Development Server

Source: https://github.com/tacho87/puremix/blob/main/docs/index.html

Navigates into the application directory and starts the development server. The server typically runs on http://localhost:3000 and supports hot reloading for instant feedback on code changes.

```bash
cd my-app
npm run dev

# Server starts at http://localhost:3000
# Hot reload enabled - changes reflect instantly!
```

--------------------------------

### Loader with Query Parameters Example

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

Example of a loader function that accesses query parameters from the request URL. It demonstrates extracting 'category' and 'sort' parameters to fetch related products.

```javascript
// URL: /products/123?category=electronics&sort=price
async function loadProduct(request) {
  const productId = request.params.id;      // "123"
  const category = request.query.category;  // "electronics"
  const sortBy = request.query.sort;        // "price"

  // Use in your logic
  const product = await getProduct(productId);
  const related = await getRelatedProducts(category, sortBy);

  return { data: { product, related } };
}
```

--------------------------------

### Start Puremix Development Server

Source: https://github.com/tacho87/puremix/blob/main/CLAUDE.MD

Provides the command to start the development server for the puremix project. This is essential for accessing test routes and observing debugging information.

```bash
# Start development server
cd tests/projects/comprehensive-test/
npm run dev
```

--------------------------------

### Puremix Installation: React and React DOM

Source: https://github.com/tacho87/puremix/blob/main/FRAMEWORK_GUIDE.md

Install the necessary React and React DOM packages for building interactive user interfaces within your Puremix project. This command uses npm for package management.

```bash
npm install react react-dom
```

--------------------------------

### Catch-All Route Handling in PureMix

Source: https://github.com/tacho87/puremix/blob/main/CLAUDE.MD

Illustrates how to implement catch-all routes in PureMix using the `[...slug].puremix` file naming convention. It shows how to capture multiple path segments into an array and handle different documentation paths based on the segments.

```html
<!-- File: app/routes/docs/[...slug].puremix -->
<!-- URL: /docs/api/users/create → slug: ["api", "users", "create"] -->
<!-- URL: /docs/guide → slug: ["guide"] -->

<loader>
  async function loadDocumentation(request) {
    const pathSegments = request.params.slug || [];
    const docPath = pathSegments.join('/');

    // Handle different documentation paths
    if (pathSegments[0] === 'api') {
      const apiDocs = await getAPIDocumentation(pathSegments.slice(1));
      return { data: { type: 'api', docs: apiDocs } };
    } else if (pathSegments[0] === 'guide') {
      const guide = await getGuide(pathSegments.slice(1));
      return { data: { type: 'guide', docs: guide } };
    }

    return { data: { type: 'general', path: docPath } };
  }
</loader>
```

--------------------------------

### PureMix Syntax Grammar Example (TextMate)

Source: https://github.com/tacho87/puremix/blob/main/PLUGIN_DEVELOPMENT.md

An example of a TextMate grammar definition for PureMix files. It outlines the structure for defining syntax highlighting rules, including supported tags, script blocks with embedded languages, and template expressions.

```json
{
  "scopeName": "source.puremix",
  "patterns": [
    { "include": "#tags" },
    { "include": "#script-blocks" },
    { "include": "#expressions" },
    { "include": "#embedded-languages" }
  ],
  "repository": {
    "tags": {
      "patterns": [
        { "name": "entity.name.tag.puremix", "match": "<\\/?(layout|loader|imports|head|loading)\\b" },
        { "name": "entity.name.tag.puremix", "match": "<script\\s+(server|client)\\b" },
        { "name": "entity.name.tag.puremix", "match": "<script\\s+server\\s+lang=\\"python\\\"\\b" }
      ]
    },
    "script-blocks": {
      "patterns": [
        { "include": "source.js" },
        { "include": "source.python" }
      ]
    },
    "expressions": {
      "patterns": [
        { "name": "meta.template.expression.puremix", "begin": "{", "end": "}", "patterns": [{"include": "source.js"}] }
      ]
    },
    "embedded-languages": {
      "patterns": [
        { "include": "text.html.basic" },
        { "include": "source.js" },
        { "include": "source.python" }
      ]
    }
  }
}
```

--------------------------------

### Example Environment Variables for Production

Source: https://github.com/tacho87/puremix/blob/main/docs/documentation.html

An example of environment variables typically used for a PureMix production deployment. These variables configure the Node.js environment, server port, host, database connection, Python workers, and debugging verbosity.

```env
# Create .env.production
NODE_ENV=production
PORT=3000
HOST=0.0.0.0
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
PYTHON_WORKERS=4
VERBOSE_DEBUG=false
```
Tokens:
Raw