Skip to content

CarGDev/strata-compile

BranchesTags

Repository files navigation

Strata

Static Template Rendering Architecture

Strata is a compile-time web framework that resolves templates to pure HTML at build time. Zero runtime framework overhead. Maximum performance.

 ╔═══════════════════════════════════════════════════════╗
 ║   ███████╗████████╗██████╗  █████╗ ████████╗ █████╗   ║
 ║   ██╔════╝╚══██╔══╝██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗  ║
 ║   ███████╗   ██║   ██████╔╝███████║   ██║   ███████║  ║
 ║   ╚════██║   ██║   ██╔══██╗██╔══██║   ██║   ██╔══██║  ║
 ║   ███████║   ██║   ██║  ██║██║  ██║   ██║   ██║  ██║  ║
 ║   ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝  ║
 ╚═══════════════════════════════════════════════════════╝

Table of Contents

Philosophy

Strata follows three core principles:

  1. Compile-Time Resolution: All template logic is resolved during build, not at runtime
  2. Zero Runtime Overhead: Output is pure HTML/CSS/JS with no framework dependencies
  3. Strict Separation of Concerns: Each file type has a single responsibility

Design Pattern: STRC

Strata implements the STRC Pattern (Static Template Resolution with Compartmentalized Layers):

┌─────────────────────────────────────────────────────────────┐
│                      BUILD TIME                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
│  │   .strata    │◄───│ .compiler.sts│◄───│ .service.sts │   │
│  │  (Template)  │    │  (Variables) │    │   (Logic)    │   │
│  └──────────────┘    └──────────────┘    └──────────────┘   │
│         │                   │                   │           │
│         │                   │                   │           │
│         ▼                   ▼                   ▼           │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              STATIC COMPILER                        │    │
│  │   Resolves all variables, loops, and conditionals   │    │
│  └─────────────────────────────────────────────────────┘    │
│                           │                                 │
└───────────────────────────┼─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      RUNTIME                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    PURE HTML                        │    │
│  │         No Strata syntax, no framework code         │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

STRC Layer Responsibilities

Layer File Extension Purpose Execution
Template .strata HTML structure with directives Build time
Compiler .compiler.sts Variable definitions, data Build time
Service .service.sts Business logic, API calls Build time*
Runtime .service.sts Optional browser interactivity Runtime

*Services can define both build-time data fetching and optional runtime interactivity.

Installation

Prerequisites

  • Go 1.21+ (for building the compiler)
  • Node.js 18+ (for project scaffolding)

Install Strata CLI

# Clone the repository
git clone https://github.com/CarGDev/strata.git
cd strata

# Build the compiler
make build

# Install globally
make install

This installs:

  • strata - The main CLI compiler
  • create-strata - Project scaffolding tool

Quick Start

Create a New Project

# Create a new Strata project
npx create-strata-compile my-app

# Navigate to project
cd my-app

# Install dependencies
npm install

# Start development server
npm run dev

Open http://localhost:3000 to see your app.

Build for Production

npm run build

Output is in the dist/ folder - pure static HTML ready for any hosting.

CLI Commands

Main CLI (strata)

# Development server with HMR
strata-compile dev [--port 3000] [--open]

# Production build
strata-compile build [--output dist]

# Preview production build
strata-compile preview [--port 4000]

Generator Commands

Generate new files with the correct structure:

# Generate a component
strata-compile gcomponent Button
# Creates: src/components/Button/
#   ├── Button.strata
#   ├── Button.compiler.sts
#   ├── Button.service.sts
#   └── Button.scss

# Generate a page
strata-compile gpage about
# Creates: src/pages/about/
#   ├── about.strata
#   ├── about.compiler.sts
#   ├── about.service.sts
#   └── about.scss

# Generate a service
strata-compile gservice auth
# Creates: src/services/auth.service.sts

# Generate an API contract
strata-compile gapi users
# Creates: src/api/users.api.sts

# Generate a utility
strata-compile gutil format
# Creates: src/utils/format.sts

# Generate a store
strata-compile gstore cart
# Creates: src/stores/cart.store.sts

Shorthand Commands

strata-compile gc Button    # component
strata-compile gp about     # page
strata-compile gs auth      # service
strata-compile ga users     # api
strata-compile gu format    # util

Project Structure

my-app/
├── src/
│   ├── components/          # Reusable UI components
│   │   └── Button/
│   │       ├── Button.strata
│   │       ├── Button.compiler.sts
│   │       ├── Button.service.sts
│   │       └── Button.scss
│   │
│   ├── pages/               # Route-based pages
│   │   ├── index/
│   │   │   ├── index.strata
│   │   │   ├── index.compiler.sts
│   │   │   ├── index.service.sts
│   │   │   └── index.scss
│   │   └── about/
│   │       └── ...
│   │
│   ├── services/            # Business logic
│   │   └── auth.service.sts
│   │
│   ├── api/                 # API contracts
│   │   └── users.api.sts
│   │
│   ├── stores/              # State management
│   │   └── cart.store.sts
│   │
│   ├── utils/               # Pure utilities
│   │   └── format.sts
│   │
│   └── assets/
│       └── styles/
│           ├── _variables.scss
│           └── global.scss
│
├── public/                  # Static assets (copied as-is)
├── dist/                    # Build output
├── strataconfig.ts          # Project configuration
└── package.json

File Types

.strata - Template Files

Pure HTML structure with Strata directives. No logic, no JavaScript.

<template>
  <main class="page">
    <h1>{ title }</h1>
    <p>{ description }</p>
  </main>
</template>

Rules:

  • Must contain a single <template> root
  • Can only import other .strata files
  • Cannot contain <script> tags
  • All variables come from .compiler.sts

.compiler.sts - Compiler Files

Defines variables available to the template. Executed at build time.

// page.compiler.sts
export const title = 'My Page';
export const description = 'Welcome to my page';

// Arrays for loops
export const items = [
  { id: 1, name: 'Item 1' },
  { id: 2, name: 'Item 2' },
];

// Booleans for conditionals
export const isProduction = false;
export const showBanner = true;

Rules:

  • All exports become template variables
  • Can import from .service.sts, .api.sts, .sts
  • Cannot import from .strata files
  • Runs during compilation, not in browser

.service.sts - Service Files

Business logic layer. Can define both build-time and runtime behavior.

// auth.service.sts

// Build-time: fetch data during compilation
export async function fetchUserData() {
  const response = await fetch('https://api.example.com/user');
  return response.json();
}

// Runtime: browser interactivity (optional)
const mount = function() {
  document.getElementById('btn').addEventListener('click', () => {
    console.log('Clicked!');
  });
};

return { mount };

Rules:

  • Can import from .api.sts, .sts
  • Cannot import from .strata, .compiler.sts

.api.sts - API Contract Files

Declarative API endpoint definitions.

// users.api.sts
export const endpoints = {
  getUsers: {
    method: 'GET',
    url: '/api/users',
    cache: 3600
  },
  createUser: {
    method: 'POST',
    url: '/api/users',
    body: { name: 'string', email: 'string' }
  }
};

.sts - Utility Files

Pure functions with no side effects. Can be imported anywhere.

// format.sts
export function formatDate(date) {
  return new Date(date).toLocaleDateString();
}

export function capitalize(str) {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

.scss - Style Files

Scoped styles for components/pages. Standard SCSS syntax.

// Button.scss
.button {
  padding: 0.5rem 1rem;
  border-radius: 4px;

  &:hover {
    opacity: 0.9;
  }
}

Template Syntax

Variable Interpolation

{ variableName }

Variables are defined in the corresponding .compiler.sts file.

<!-- page.strata -->
<h1>{ title }</h1>
<p>Author: { author.name }</p>
// page.compiler.sts
export const title = 'Hello World';
export const author = { name: 'John Doe' };

Output:

<h1>Hello World</h1>
<p>Author: John Doe</p>

Loops: s-for

{ s-for item in items }
  <!-- content repeated for each item -->
{ /s-for }

With index:

{ s-for item, index in items }
  <div>#{ index }: { item.name }</div>
{ /s-for }

Example:

<!-- page.strata -->
<ul>
  { s-for user in users }
    <li>{ user.name } - { user.email }</li>
  { /s-for }
</ul>
// page.compiler.sts
export const users = [
  { name: 'Alice', email: 'alice@example.com' },
  { name: 'Bob', email: 'bob@example.com' },
];

Output:

<ul>
  <li>Alice - alice@example.com</li>
  <li>Bob - bob@example.com</li>
</ul>

Conditionals: s-if / s-elif / s-else

{ s-if condition }
  <!-- shown if condition is true -->
{ s-elif otherCondition }
  <!-- shown if otherCondition is true -->
{ s-else }
  <!-- shown if all conditions are false -->
{ /s-if }

Example:

{ s-if isAdmin }
  <div class="admin-panel">Admin Controls</div>
{ s-elif isModerator }
  <div class="mod-panel">Moderator Controls</div>
{ s-else }
  <div class="user-panel">User Dashboard</div>
{ /s-if }
// page.compiler.sts
export const isAdmin = false;
export const isModerator = true;

Output:

<div class="mod-panel">Moderator Controls</div>

Negation

{ s-if !isLoggedIn }
  <a href="/login">Please log in</a>
{ /s-if }

Comparison Operators

{ s-if count > 0 }
  <p>You have { count } items</p>
{ /s-if }

{ s-if status === 'active' }
  <span class="badge">Active</span>
{ /s-if }

Supported operators: ===, ==, !==, !=, >, <, >=, <=

Component Imports (Coming Soon)

{ s-imp "@components/Button" }

Examples

Basic Page

<!-- src/pages/index/index.strata -->
<template>
  <main class="home">
    <h1>{ title }</h1>
    <p>{ subtitle }</p>

    <section class="features">
      { s-for feature in features }
        <div class="feature-card">
          <span>{ feature.icon }</span>
          <h3>{ feature.name }</h3>
          <p>{ feature.description }</p>
        </div>
      { /s-for }
    </section>

    { s-if showCTA }
      <a href="/signup" class="cta">Get Started</a>
    { /s-if }
  </main>
</template>
// src/pages/index/index.compiler.sts
export const title = 'Welcome to My App';
export const subtitle = 'Build faster, deploy smarter';
export const showCTA = true;

export const features = [
  { icon: '⚡', name: 'Fast', description: 'Blazing fast performance' },
  { icon: '🔒', name: 'Secure', description: 'Built-in security' },
  { icon: '📦', name: 'Simple', description: 'Easy to use' },
];

Page with Runtime Interactivity

<!-- src/pages/counter/counter.strata -->
<template>
  <main class="counter-page">
    <h1>Counter Example</h1>
    <button id="counterBtn">Click Me</button>
    <p>Count: <span id="count">0</span></p>
  </main>
</template>
// src/pages/counter/counter.service.sts
const mount = function() {
  const btn = document.getElementById('counterBtn');
  const countEl = document.getElementById('count');
  let count = 0;

  btn.addEventListener('click', function() {
    count++;
    countEl.textContent = count;
  });
};

return { mount };

Build-Time Data Fetching

// src/pages/pokemon/pokemon.compiler.sts
export const title = 'Pokemon Gallery';

// This data is fetched at BUILD TIME, not runtime
export const pokemons = [
  { id: 1, name: 'Bulbasaur', type: 'grass' },
  { id: 4, name: 'Charmander', type: 'fire' },
  { id: 7, name: 'Squirtle', type: 'water' },
];

export const totalCount = pokemons.length;
<!-- src/pages/pokemon/pokemon.strata -->
<template>
  <main class="pokemon-page">
    <h1>{ title }</h1>
    <p>Showing { totalCount } Pokemon</p>

    <div class="grid">
      { s-for pokemon in pokemons }
        <div class="card">
          <h3>{ pokemon.name }</h3>
          <span class="type">{ pokemon.type }</span>
        </div>
      { /s-for }
    </div>
  </main>
</template>

Import Hierarchy

Strata enforces a strict import hierarchy to maintain separation of concerns:

┌─────────────┐
│   .strata   │  Can only import: .strata
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ .compiler.sts   │  Can import: .service.sts, .api.sts, .sts
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  .service.sts   │  Can import: .api.sts, .sts
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│    .api.sts     │  Can import: .sts
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│      .sts       │  Can import: .sts only
└─────────────────┘

Violations will cause build errors.

Development

Running Tests

make test

Building from Source

# Build compiler
make build

# Build and install
make install

# Clean build artifacts
make clean

Project Configuration

// strataconfig.ts
export default {
  // Development server port
  port: 3000,

  // API proxy for development
  api: {
    baseUrl: 'http://localhost:8080',
    proxy: true
  },

  // Build output directory
  output: 'dist',

  // Enable source maps in development
  sourceMaps: true
};

License

Proprietary - All Rights Reserved

This software is currently in development and is not available for public use, modification, or distribution. See LICENSE for details.

Links

Strata - Code Faster. Load Quick. Deploy ASAP.

About

No description, website, or topics provided.

Resources

Readme

License

View license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages