Rustelo/templates/shared/README.md

Shared Asset Repository

This directory contains the master repository of all assets that can be used by Rustelo implementation templates. This follows the DRY principle - all assets are defined once here and included by template variants as needed.

Structure

shared/
├── scripts/              # Setup, build, database, deployment scripts
│   ├── setup/           # Installation and setup scripts
│   ├── build/           # Build and compilation scripts
│   ├── database/        # Database management scripts
│   ├── deploy/          # Deployment scripts
│   ├── testing/         # Testing and quality assurance scripts
│   └── utils/           # Utility scripts
├── configs/             # Configuration templates
│   ├── base/            # Base configurations (app.toml, database.toml, etc.)
│   ├── environments/    # Environment-specific configs (dev, prod, staging)
│   ├── features/        # Feature-specific configurations (auth, content, etc.)
│   └── examples/        # Example configurations
├── docker/              # Docker files for different purposes
│   ├── Dockerfile.dev   # Development Docker file
│   └── Dockerfile.cross # Cross-compilation Docker file
├── content/             # Sample content and localization
│   ├── locales/         # Localization files
│   ├── blog/            # Sample blog posts
│   └── pages/           # Sample pages
├── docs/                # Documentation templates
├── public/              # Public assets (images, logos, etc.)
├── src/                 # Source code templates
│   ├── main.rs.template # Main application entry point
│   └── lib.rs.template  # Library entry point
├── justfile.template    # Just task runner configuration
├── package.json.template # Node.js package configuration
├── Cargo.toml.template  # Rust package configuration
├── unocss.config.ts.template # UnoCSS configuration
└── rustelo-deps.toml.template # Rustelo dependency configuration

Asset Inclusion System

Template variants use inclusion/exclusion patterns to select which assets they need:

Template Manifest Format

Each template variant has a manifest that specifies:

{
  "name": "basic",
  "includes": [
    "shared/scripts/setup/*.sh",
    "shared/scripts/build/build-docs.sh",
    "shared/configs/base/*.toml",
    "shared/docker/Dockerfile.dev"
  ],
  "excludes": [
    "shared/scripts/enterprise/*",
    "shared/configs/features/advanced/*"
  ],
  "template_files": [
    "shared/justfile.template",
    "shared/package.json.template",
    "shared/Cargo.toml.template",
    "shared/unocss.config.ts.template"
  ]
}

Template Variables

All .template files support variable substitution:

• {{project_name}} - Project name
• {{project_name_snake}} - Project name in snake_case
• {{template_variant}} - Template variant (basic, enterprise, etc.)
• {{rustelo_version}} - Rustelo framework version
• {{generation_timestamp}} - When the template was generated
• {{asset_source}} - Where assets came from (local, remote, etc.)

Adding New Assets

1. Add the asset file to the appropriate subdirectory
2. Use template variables if the asset needs customization
3. Update template manifests to include the new asset where appropriate
4. Test with different variants to ensure proper inclusion

Maintaining DRY Principle

• Single source of truth: All assets live in shared/
• Template variants include, don't duplicate: Templates specify what to include, not what to copy
• Easy updates: Modify once in shared/, all templates benefit
• Clear ownership: Each asset has one canonical location

Asset Types

Scripts (shared/scripts/)

Executable shell scripts for various tasks:

• Setup and installation
• Build and compilation
• Database management
• Deployment
• Testing and validation

Configurations (shared/configs/)

Configuration file templates:

• Base configurations for common settings
• Environment-specific configs
• Feature-specific configs
• Example configurations

Templates (shared/*.template)

Core project file templates:

• Build system configuration
• Package management
• CSS/styling configuration
• Framework dependency management

Content (shared/content/)

Sample content and localization:

• Blog posts
• Page content
• Localization files
• Menu structures

Template Resolution Process

1. Template selection: User chooses a template variant
2. Manifest loading: CLI loads the template's manifest
3. Asset resolution: CLI processes include/exclude patterns
4. File copying: Matching assets are copied to target project
5. Variable substitution: Template variables are replaced in .template files
6. File renaming: .template extensions are removed

This approach ensures maintainability, reduces duplication, and provides flexibility for different implementation needs.