Salesive Development Tools

A powerful CLI tool and development toolkit for building, managing, and deploying Salesive templates.

Features

• 🎨 Template Management: Create, validate, and deploy Salesive templates
• 🔐 API Authentication: Secure authentication with Salesive Themes API
• ✅ Configuration Validation: Validate your template configuration files
• 🚀 One-Command Deploy: Package and deploy templates with cook
• 🔄 Auto-Update Check: Automatically notifies you of new versions
• 🔧 Vite Plugin: Inject configuration into your React applications
• 🪝 React Hooks: Easy access to configuration data in components

Installation

Global Installation (Recommended for CLI)

npm install -g salesive-dev-tools
# or
yarn global add salesive-dev-tools
# or
pnpm add -g salesive-dev-tools
# or
bun add -g salesive-dev-tools

Local Installation (For Vite Plugin)

npm install salesive-dev-tools
# or
yarn add salesive-dev-tools
# or
pnpm add salesive-dev-tools

Usage

Setup in Vite Configuration

// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { salesiveConfigPlugin } from "salesive-dev-tools";

export default defineConfig({
    plugins: [react(), salesiveConfigPlugin()],
});

Create a Salesive Config File

Create a salesive.config.json file in the root of your project:

{
    "name": "my-project",
    "version": "1.0.0",
    "description": "My Project Description",
    "variables": {
        "color-brand-primary": "#0d65d9",
        "color-brand-primary-x": "#e6f6ff",
        "font-brand-space": "Space Grotesk",
        "app-name": "My App",
        "app-description": "My awesome application",
        "app-logo": "https://example.com/logo.png",
        "app-favicon": "https://example.com/favicon.ico"
    }
}

Using the React Hook

import { useSalesiveConfig } from "salesive-dev-tools";

function MyComponent() {
    // Get a specific variable value
    const appName = useSalesiveConfig("app-name");
    const brandColor = useSalesiveConfig("color-brand-primary");

    // Or get all variables
    const allVariables = useSalesiveConfig();

    return (
        <div style={{ color: brandColor }}>
            <h1>{appName}</h1>
        </div>
    );
}

Dynamic Configuration Updates

You can update the Salesive configuration at runtime and all components using the configuration will automatically update:

import { updateSalesiveConfig, setSalesiveConfig } from "salesive-dev-tools";

// Update a specific variable
setSalesiveConfig("app-name", "My Updated App Name");

// Update multiple variables at once (merges with existing config)
updateSalesiveConfig({
    variables: {
        "color-brand-primary": "#ff0000",
        "app-description": "Updated description",
    },
});

// Use a function to update based on previous state
updateSalesiveConfig((prevConfig) => ({
    ...prevConfig,
    variables: {
        ...prevConfig.variables,
        "app-name": `${prevConfig.variables["app-name"]} - Updated`,
    },
}));

// Replace the entire config (no merging)
updateSalesiveConfig(newConfig, { merge: false });

// Advanced usage with options
updateSalesiveConfig(newConfig, {
    merge: true, // Whether to merge with existing config (default: true)
    notify: true, // Whether to notify components to update (default: true)
});

Integration with React Router

You can use dynamic configuration with React Router to create route-specific themes:

import { Outlet, useLocation } from "react-router-dom";
import { setSalesiveConfig } from "salesive-dev-tools";

// Route-specific theme switcher
function ThemeManager() {
    const location = useLocation();

    useEffect(() => {
        // Update theme based on current route
        if (location.pathname.startsWith("/admin")) {
            setSalesiveConfig("color-brand-primary", "#2d3748");
        } else if (location.pathname.startsWith("/marketing")) {
            setSalesiveConfig("color-brand-primary", "#e53e3e");
        } else {
            setSalesiveConfig("color-brand-primary", "#0d65d9");
        }
    }, [location.pathname]);

    return <Outlet />;
}

Using the Helper Function (for non-component code)

import { getSalesiveConfig } from "salesive-dev-tools";

// Get a specific variable value
const appName = getSalesiveConfig("app-name");

// Or get all variables
const allVariables = getSalesiveConfig();

What Gets Injected?

The plugin performs several injections into your HTML:

1. Page Title: From variables.app-name
2. Meta Description: From variables.app-description
3. Favicon: From variables.app-favicon
4. CSS Variables: All entries in variables are injected as CSS custom properties
5. Global JavaScript Object: The entire config is available at window.SALESIVE_CONFIG

Integration with React Router

For projects using React Router, you can combine this plugin with a routing setup. This works well with the nested route structure pattern where components are organized into a layout hierarchy.

Example routing structure:

// router.jsx
import { createBrowserRouter } from "react-router-dom";
import App from "./App";
import HomePage from "./pages/Home";

const router = createBrowserRouter([
    {
        path: "/",
        element: <App />,
        children: [
            { index: true, element: <HomePage /> },
            // ...other routes
        ],
    },
]);

export default router;

Options

The salesiveConfigPlugin accepts the following options:

salesiveConfigPlugin({
    // Custom path to your config file (default: 'salesive.config.json' in project root)
    configPath: "./path/to/config.json",
});

Development Mode Only

The plugin only runs during development (vite dev) and is automatically disabled for production builds to keep your production code clean.

CLI Commands

Quick Start

# 1. Set up authentication
salesive auth set-token

# 2. Initialize a new template (or use existing)
salesive init

# 3. Validate your configuration
salesive validate

# 4. Deploy your template
salesive cook

Authentication

Manage your Salesive API credentials for deploying templates.

# Set your Salesive API token
salesive auth set-token

# Check authentication status
salesive auth status

# Verify API key with server
salesive auth verify

# Clear your token if needed
salesive auth clear-token

Creating New Projects

# Initialize a new Salesive project with interactive prompts
# (Select Build Tool, Framework, and Package Manager)
salesive init

# Initialize in the current directory (scaffolding)
salesive init --current

# Create a project with specific options (skips prompts)
salesive init --name my-project --build-tool vite --framework react

# Force creation even if directory exists
salesive init --name existing-dir --force

Development

# Start development server with config file watching
salesive dev

# Specify a custom project path
salesive dev --path ./my-project

# Specify a custom config file
salesive dev --config ./custom-config.json

The development server provides:

• Hot Reloading: Automatically restarts when configuration changes
• Beautiful Logs: Clean, colored output
• Keyboard Shortcuts:
  • [r]: Restart the server
  • [q]: Quit the CLI
  • Ctrl+C: Exit gracefully

Template Deployment (Cook)

The cook command packages and deploys your Salesive template to the themes API. It automatically runs your project build script (e.g., npm run build) before packaging.

# Deploy template from current directory (builds first)
salesive cook

# Skip the automatic build step
salesive cook --no-build

# Deploy from a specific path
salesive cook --path ./my-template

# Use a custom config file
salesive cook --config ./custom-config.json

# Keep temporary files for debugging
salesive cook --keep-temp

# Show detailed error information
salesive cook --verbose

What gets deployed:

• All template files (HTML, CSS, JS, images, etc.)
• salesive.config.json (required)
• salesive.form.json (optional, but recommended)

Automatic exclusions:

• node_modules/
• .git/
• .salesive-temp/
• *.log
• .DS_Store

Generate Form Configuration:

If you don't have a salesive.form.json, generate one at: https://template-form.salesive.com

Configuration Validation

Validate your salesive.config.json before deployment:

# Validate current project
salesive validate

# Validate specific project
salesive validate --path ./my-project

# Validate specific config file
salesive validate --config ./custom-config.json

# Show verbose output
salesive validate --verbose

Validation checks:

• Required fields: name, version, description
• Name format: lowercase, no spaces (use hyphens)
• Version format: semantic versioning (x.x.x)
• Variables structure

Configuration File Format

Your salesive.config.json must follow this structure:

{
    "name": "my-template",
    "version": "1.0.0",
    "description": "My awesome template",
    "author": "Your Name",
    "license": "MIT",
    "website": "https://example.com",
    "icon": "https://example.com/icon.png",
    "email": "[email protected]",
    "variables": {
        "primary-color": "#0d65d9",
        "secondary-color": "#e6f6ff",
        "font-family": "Space Grotesk"
    }
}

Available Options

Cook Options

| Option | Description | | ------------------------ | ------------------------------------------------------- | | -p, --path <path> | Path to template directory (default: current directory) | | -c, --config <path> | Path to salesive.config.json file | | --no-build | Skip the automatic build step | | -b, --build-dir <path> | Alias for --out-dir to specify build directory | | -k, --keep-temp | Keep temporary files after cooking | | -v, --verbose | Show verbose output and detailed error information |

Auth Options

| Option | Description | | --------------- | ---------------------------------------------------- | | -v, --verbose | Show detailed error information (for verify command) |

Init Options

| Option | Description | | --------------------------------- | -------------------------------------- | | -n, --name <name> | Project name | | -c, --current | Initialize in current directory | | -b, --build-tool <tool> | Build tool (vite) | | --framework <framework> | Framework (react) | | -p, --package-manager <manager> | Package manager (npm, yarn, bun, pnpm) | | -f, --force | Overwrite existing directory | | -v, --verbose | Show verbose output |

Validate Options

| Option | Description | | --------------------- | --------------------------------- | | -p, --path <path> | Path to project directory | | -c, --config <path> | Path to salesive.config.json file | | -v, --verbose | Show verbose output |

Automatic Updates

The CLI automatically checks for updates once every 24 hours and notifies you when a new version is available.

┌──────────────────────────────────────────────────────────┐
│  Update available!  0.0.1 → 1.0.0                        │
│  Run npm install -g salesive-dev-tools to update         │
└──────────────────────────────────────────────────────────┘

Error Handling

The CLI provides detailed error messages with actionable suggestions:

✖ API key verification failed

✗ Error 401: Unauthorized
  Invalid API key format

💡 Suggestion:
  • Invalid or expired API key
  • Run salesive auth set-token to update your API key
  • Ensure the API key starts with sk-

Use the --verbose flag with any command to see detailed error information.

Troubleshooting

Common Issues

Authentication Errors:

# Verify your API key is valid
salesive auth verify

# Set a new API key if needed
salesive auth set-token

Configuration Errors:

# Validate your config file
salesive validate

# Check for common issues:
# - Name must be lowercase with no spaces
# - Version must follow x.x.x format
# - All required fields must be present

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT