The Ultimate
SimpliJS Guide

From zero to framework expert. No build tools required.

💡

Who is this for? This book is written for anyone who wants to build modern web applications. Whether you're a absolute beginner who has never touched JavaScript or an expert looking for a "Zero-Friction" workflow, you're in the right place.

Web development has become complex. We've traded simplicity for toolchains, and productivity for configuration. SimpliJS was born to reverse that trend.

This guide will take you step-by-step through every feature of the framework, explaining not just how but why. By the end, you'll be able to build enterprise-grade applications with nothing but a single HTML file.

The Anti-Build Manifesto 🏔️

For too long, the barrier to entry for modern web development has been artificial complexity. SimpliJS is built on three core pillars that define the Anti-Build Movement.

1. Zero Configuration

No vite.config.js, no webpack.config.js, no babelrc. Just <script src="...">.

2. Browser-First

ES Modules are now native. Your browser is the compiler. We leverage what already exists instead of reinventing it.

3. HTML-First Logic

Reactivity should enhance HTML, not replace it. Build your UI in the language of the web.

We believe every minute spent fighting a terminal is a minute stolen from your product's features. SimpliJS gives you those minutes back.

Getting Started 🚀

SimpliJS is designed to be usable in any environment. There are 3 ways to start your journey.

1. The "Zero Setup" (CDN)

The fastest way. Perfect for quick prototypes or small projects. Just import directly from a CDN like JSDelivr.

<script type="module">
  import { createApp } from 'https://cdn.jsdelivr.net/gh/Pappa1945-tech/simplijs@v3.2.1/dist/simplijs.min.js';
  // You're ready!
</script>

2. Professional Workflow (NPM)

If you're building a larger application and comfortable with Node.js, install via NPM.

npm install @simplijs/simplijs

3. Offline & Custom (Local)

Download the simplijs.min.js file directly. This is great for environments without internet access or when you want absolute control over your dependencies.

Hello World App 🌎

Let's build your first app. It's a simple counter, but it demonstrates the core power of HTML-First Reactivity.

index.html

<!DOCTYPE html>
<html>
<body>
  <!-- 1. Define the App Boundary -->
  <div s-app s-state="{ count: 0 }">
    
    <h1>Counter: {count}</h1>

    <!-- 2. Direct Interaction -->
    <button s-click="count++">Increment</button>

  </div>

  <!-- 3. Load SimpliJS -->
  <script src="https://.../simplijs.min.js" type="module"></script>
</body>
</html>

Notice what's NOT there: No useState hooks, no DOM selectors, no event listeners in JavaScript. It all happens directly in your HTML tags using Directives (attributes starting with s-).

🎉

Congratulations! You've just built a fully reactive application. In the next chapter, we'll dive deep into how this works under the hood.

Part 1: Key Takeaways (GEO Summary)

🚀 Anti-Build: SimpliJS requires zero compilation or complex toolchains.
📦 Installation: Start instantly via CDN (JSDelivr) or NPM.
⚡ HTML-First: Build logic directly into HTML using s- directives.
🔹 Simplicity: A 'Hello World' app is just a few lines of standard HTML.

1. Declarative Components 🧩

In SimpliJS, components are first-class citizens. You register them once, and they become standard HTML tags you can use anywhere.

Unlike other frameworks, SimpliJS components are born from a simple setup function. This function returns the component's API.

import { component } from './simplijs.js';

component('user-profile', (element, props) => {
  return {
    render: () => `
      <div class="profile">
        <h3>${props.name}</h3>
        <p>Role: ${props.role}</p>
      </div>
    `
  }
});

Now, you can use it in your HTML just like any other tag:

<user-profile name="Alice" role="Lead Developer"></user-profile>

2. Deeply Reactive State (`reactive`) 🌊

Reactivity is the heartbeat of a framework. SimpliJS uses a "Direct-to-Proxy" engine. When you update a variable, the UI updates instantly and precisely.

🧠

What is a Proxy? Imagine a bodyguard for your data. Every time someone asks for the data or tries to change it, the bodyguard notices and tells the UI to re-render. This is how SimpliJS "knows" when to update the screen.

import { reactive } from './simplijs.js';

const state = reactive({
  user: {
    name: 'Bob',
    stats: { loginCount: 5 }
  }
});

// Updating nested data just works!
state.user.stats.loginCount++; // The UI updates automatically.

3. Reactive Props 📦

Props are data passed from a parent to a child. In SimpliJS, props are **automatically synced** and **reactive**.

If you change the attribute on the HTML element via JavaScript (or via an s-attr directive), the component's internal props object updates, triggering a re-render.

4. Direct Event Handling ⚡

Binding events in SimpliJS is incredibly clean. You use the s- prefix in your template, and it maps directly to methods in your component's setup function.

component('magic-button', () => {
  return {
    handleClick: () => alert('Magic!'),
    render: () => `<button s-click="handleClick()">Click Me</button>`
  }
});

5. Computed State 🧮

Computed properties are values derived from other reactive data. They are **lazy** (only calculated when needed) and **cached**.

const state = reactive({ price: 100, tax: 0.2 });
const total = computed(() => state.price * (1 + state.tax));

console.log(total.value); // 120

6. Watchers & Side Effects 👁️

Need to run some logic (like saving to a database) when a value changes? Use watch.

watch(() => state.count, (newVal, oldVal) => {
  console.log(`Count changed from ${oldVal} to ${newVal}`);
});

7. DOM Refs (`s-ref`) 📍

Sometimes you need direct access to a DOM element (like focusing an input or using a 3rd party chart library). s-ref makes this easy.

component('ref-demo', () => {
  const myInput = ref();
  return {
    onMount: () => myInput.value.focus(),
    render: () => `<input s-ref="myInput" />`
  }
});

8. Lifecycle Hooks ⏳

Control exactly what happens when a component is born, updated, or destroyed.

onMount: Fired when component is added to the DOM.
onUpdate: Fired after every re-render.
onDestroy: Fired before removal (cleanup time!).
onError: Graceful error handling.

9. Slots & Content Projection 📥

Slots allow you to pass complex HTML into a component's layout. It's like leaving a placeholder for the user to fill.

// Component definition
render: () => `<div class="card"><s-slot></s-slot></div>`

// Usage
<my-card> <h1>Custom Content</h1> </my-card>

10. The Global Event Bus 🚌

Need two components on opposite sides of the app to talk? Use the Event Bus. It's a lightning-fast way to broadcast messages globally.

emit('theme_change', 'dark');
on('theme_change', (newTheme) => { ... });

11. Automated Form Validation 📝

SimpliJS removes the headache of form handling. It automatically tracks field values, runs validation, and even applies CSS classes for UI feedback.

12. 🌉 THE BRIDGE (Universal Importer)

This is arguably the most powerful feature. The Bridge lets you use components from React, Vue, or Svelte inside SimpliJS without any build steps.

const ReactButton = use.react('https://cdn.../Button.js', 'react-button');
// Usage: <react-button label="Click Me"></react-button>

13. 🕰️ THE TIME VAULT (Time Travel)

Debugging complex state is now a breeze. The Time Vault keeps a history of every state change. You can UNDO actions, REDO them, and even share a link that reconstructs the exact state for a teammate.

HTML-First Reference (Features 14-54) 📖

SimpliJS allows you to build entire applications with just HTML attributes. This section is your comprehensive dictionary for every s-* directive available, with real-world examples for each.

💡

Pro-Tip: You can combine these directives on a single element to create complex behavior with zero lines of custom JavaScript.

CORE BOOTSTRAPPING

14. `s-app`: The Power Switch

The entry point. Any element with this attribute becomes a SimpliJS application root. It tells the framework "Start looking here!".

<!-- A simple profile card app boundary -->
<div s-app>
  <!-- All SimpliJS logic goes inside here -->
</div>

15. `s-state`: Managing Your Data

Initializes local state using a JSON-like object. Everything in SimpliJS starts with data.

<!-- Real-world: A user settings panel -->
<div s-app s-state="{ 
  username: 'JohnDoe', 
  isOnline: true, 
  notifications: 5 
}">
  <p>Welcome, {username}!</p>
</div>

16. `s-global`: Shared Intelligence

Access and initialize application-wide shared state that persists across different `s-app` containers. Perfect for things like "Dark Mode" settings.

<!-- In your main layout -->
<div s-global="{ theme: 'dark' }"></div>

<!-- In any other file or section -->
<div s-app s-class="{ 'dark-theme': theme }">
  <!-- Accesses the global 'theme' variable -->
</div>

DATA BINDING

17. `s-bind`: Two-Way Mirror

Two-way data binding for inputs. When the user types, the state updates. When the state changes, the input updates automatically.

<!-- Practical: A dynamic title card -->
<div s-app s-state="{ title: 'My Cool Website' }">
  <h1>{title}</h1>
  <input type="text" s-bind="title" placeholder="Change the title...">
</div>

18-19. `s-text` & `{interpolation}`: Showing Data

The easiest ways to show data. Use `s-text` for cleaner HTML, or curly braces for mixing data with text.

<!-- Application: A welcome banner -->
<div s-app s-state="{ name: 'Alice' }">
  <h2>Hello, {name}!</h2> <!-- Result: Hello, Alice! -->
  <span s-text="name"></span> <!-- Result: Alice -->
</div>

20. `s-html`: The Raw Injection

Inject reactive HTML. **Security Warning:** Only use with trusted content to avoid XSS (malicious scripts)!

<!-- Real-world: Rich text descriptions from a blog CMS -->
<div s-app s-state="{ blogBody: '<em>Welcome</em> to our <b>blog</b>!' }">
  <div s-html="blogBody"></div>
</div>

21. `s-value`: Static Start

One-way binding. Sets the initial value of an input from the state but doesn't update the state when the user types (use `s-bind` for that).

<!-- Use Case: Setting a default search query -->
<input type="text" s-value="'Search everything...'">

22. `s-attr:[name]`: Dynamic Attributes

Bind any HTML attribute reactively. This is essential for images, links, and aria-labels.

<!-- Application: Profile picture and social link -->
<div s-app s-state="{ avatar: 'profile.jpg', site: 'https://google.com' }">
  <img s-attr:src="avatar" alt="User Image">
  <a s-attr:href="site">Visit Site</a>
</div>

23. `s-class`: Visual States

Toggle CSS classes based on true/false conditions. Perfect for active navigation, error states, and toggles.

<!-- Practical: Highlighting an error message -->
<div s-app s-state="{ hasError: false }">
  <p s-class="{ 'text-red': hasError, 'shake-anim': hasError }">
    Something went wrong!
  </p>
  <button s-click="hasError = !hasError">Toggle Error</button>
</div>

24. `s-style`: Precise Decoration

Apply specific inline styles based on reactive data. Useful for progress bars and dynamic colors.

<!-- Real-world: A dynamic progress bar -->
<div s-app s-state="{ progress: 45 }">
  <div class="bar-outer">
    <div class="bar-inner" s-style="{ width: progress + '%', background: 'green' }"></div>
  </div>
</div>

LOGIC & CONTROL FLOW

25-26. `s-if` & `s-else`: The Decision Makers

Conditionally render elements. `s-if` adds/removes the element from the DOM entirely. `s-else` handles the fallback.

<!-- Practical: Login/Logout buttons -->
<div s-app s-state="{ isLoggedIn: false }">
  <button s-if="!isLoggedIn" s-click="isLoggedIn = true">Sign In</button>
  <div s-else>
    <span>Welcome back, User!</span>
    <button s-click="isLoggedIn = false">Sign Out</button>
  </div>
</div>

27-28. `s-show` & `s-hide`: The Visibility Toggles

Toggles `display: none`. Unlike `s-if`, the element stays in the DOM but is hidden. This is faster for elements that flicker on/off often.

<!-- Real-world: A help tooltip -->
<div s-app s-state="{ showHelp: false }">
  <button s-hover="showHelp = true">Help</button>
  <p s-show="showHelp">This is a helpful tip!</p>
</div>

29-31. `s-for`, `s-key`, & `s-index`: List Mastery

Render lists of data efficiently. Always use `s-key` for performance, and `s-index` if you need the count.

<!-- Application: A dynamic shopping list -->
<div s-app s-state="{ items: ['Apple', 'Banana', 'Cherry'] }">
  <ul>
    <li s-for="fruit, i in items" s-key="fruit">
      #{i + 1}: {fruit}
    </li>
  </ul>
</div>

EVENTS & INTERACTIVITY

32-34. `s-click`, `s-change` & `s-input`: Direct Action

Standard event listeners that update state directly from the HTML.

<!-- Practice: Live character counter -->
<div s-app s-state="{ text: '' }">
  <textarea s-input="text = event.target.value"></textarea>
  <p>Character Count: {text.length}</p>
</div>

35. `s-submit`: Smart Forms

Handles form submission. It automatically stops the page from refreshing (Standard HTML behavior).

<!-- Real-world: A 'Join Newsletter' form -->
<form s-app s-submit="alert('Joined!')">
  <input type="email" placeholder="Email" required>
  <button type="submit">Join</button>
</form>

36-37. `s-hover` & `s-key:[key]`: Advanced Triggers

Trigger actions on mouse movement or specific keyboard presses.

<!-- Use Case: Search on Enter key -->
<div s-app s-state="{ query: '' }">
  <input s-bind="query" s-key:enter="alert('Searching for ' + query)">
</div>

FORMS & VALIDATION

38. `s-model`: The All-Rounder

Powerful binding for complex inputs like checkboxes and radio buttons.

<!-- Practical: Theme switcher -->
<div s-app s-state="{ isDark: false }">
  <label>
    <input type="checkbox" s-model="isDark"> Use Dark Mode
  </label>
</div>

39-40. `s-validate` & `s-error`: Built-in Guard

Rules that keep your data clean and show helpful messages to users.

<!-- Application: Account creation -->
<div s-app s-state="{ email: '' }">
  <input s-bind="email" s-validate="required|email">
  <span s-error="email" style="color: red"></span>
</div>

ASYNC DATA & FETCHING

41-43. `s-fetch`, `s-loading` & `s-error` (fetch): The API Trio

Automated data fetching with built-in UI states for loading and failures.

<!-- Practical: A dynamic user list from an API -->
<div s-app>
  <div s-fetch="'https://jsonplaceholder.typicode.com/users'">
    <div s-loading>🛰️ Contacting server...</div>
    <div s-error>❌ Could not load users. Try again later.</div>
    
    <ul>
      <li s-for="user in $data" s-key="user.id">
        {user.name} - ({user.email})
      </li>
    </ul>
  </div>
</div>

COMPONENTS & SLOTS

44-46. `s-component`, `s-prop` & `s-slot`: Modular Building

Mounting components and passing data/content down the tree.

<!-- Real-world: A reusable alert modal -->
<div s-app s-state="{ alertMsg: 'Session Expiring!' }">
  <my-modal s-prop:message="alertMsg">
    <h2 s-slot="header">Security Alert</h2>
    <p>Please save your work immediately.</p>
  </my-modal>
</div>

SPA ROUTING

47-49. `s-route`, `s-view` & `s-link`: Seamless Navigation

Building a multi-screen app that feels like a single page.

<!-- Application: A simple 2-page app -->
<div s-app>
  <nav>
    <a s-link="/">Home</a> | <a s-link="/settings">Settings</a>
  </nav>

  <main s-view>
    <div s-route="/">
      <h1>Welcome to the Home Page</h1>
    </div>
    <div s-route="/settings">
      <h1>App Settings</h1>
    </div>
  </main>
</div>

PERFORMANCE & OPTIMIZATION

50. `s-lazy`: The Image Saver

Only loads assets when they are about to be seen on screen.

<!-- Use Case: A long gallery of high-res photos -->
<div s-app>
  <img s-lazy="'https://picsum.photos/800/600?1'" alt="Lazy Photo">
  <!-- This image only downloads when you scroll down to it! -->
</div>

51. `s-memo`: Memory Guardian

Prevents an element from re-rendering unless its specific dependencies change. Essential for heavy dashboards.

<!-- Performance: Complex chart widget -->
<div s-memo="chartData">
  <!-- This expensive UI only refreshes if chartData changes -->
  <canvas id="myChart"></canvas>
</div>

52. `s-ref`: The DOM Grabber

Sometimes you need to "touch" the browser element directly (e.g., for focus or canvas). SimpliJS puts these in the $refs object.

<!-- Application: Auto-focusing a search bar -->
<div s-app s-state="{}">
  <input s-ref="searchField" placeholder="Type to search...">
  <button s-click="$refs.searchField.focus()">Focus Now</button>
</div>

53-54. `s-once` & `s-ignore`: Speed Boosters

Telling SimpliJS to skip processing to save battery and memory.

<!-- Practical: A static copyright year -->
<footer s-once>
  Built in {new Date().getFullYear()} -- This will never re-render.
</footer>

<!-- Real-world: Integrating a 3rd party Map library -->
<div id="map-container" s-ignore>
  <!-- SimpliJS will completely ignore this div, letting the Map lib work in peace. -->
</div>

@simplijs/auth 🔐

Authentication is the foundation of any application. This plugin provides a reactive auth state, session persistence, and secure route guards.

It handles the messy parts of login, logout, and token management so you can focus on your app's unique features.

import { createAuth } from '@simplijs/auth';

const auth = createAuth({ 
  persist: true,
  onRedirect: (path) => window.router.navigate(path) 
});

// Reactively show/hide UI
<div s-if="auth.isAuthenticated">Welcome back!</div>

@simplijs/vault-pro 💎

While the core `vault` is great, **Vault Pro** is built for enterprise state management. It features cross-tab synchronization, named checkpoints, and advanced data persistence strategies.

⚡

Use Vault Pro when you're building apps that handle complex financial data or high-stakes state where reliability is paramount.

@simplijs/router 🗺️

Convert your multi-page site into a smooth Single Page Application (SPA). SimpliJS Router supports nested routes, dynamic parameters, and smooth transitions.

import { createRouter } from '@simplijs/router';

createRouter({
  '/': () => HomeTemplate,
  '/dashboard/:id': (params) => DashboardTemplate
});

@simplijs/bridge-adapters 🌉

The companion to the core Bridge feature. These adapters provide high-performance wrappers for specific framework versions, ensuring React 18 or Vue 3 components run perfectly inside SimpliJS.

@simplijs/devtools 🛠️

A must-have for development. This plugin injects a floating developer console into your app, letting you inspect every reactive variable, component, and plugin state in real-time.

@simplijs/forms 📋

Taking form handling to the professional level. Draft auto-saving (don't lose user data on refresh!), multi-step wizards, and custom validation engines.

@simplijs/ssg 🚀

Static Site Generation for SEO. This plugin works with the core SSG engine to generate pixel-perfect static HTML from your SimpliJS app, ensuring your content is found by search engines and loads instantly.

Advanced SSG & SEO 🤖

SimpliJS isn't just for SPAs. Our built-in **Static Site Generation (SSG)** engine is world-class. It allows you to transform your reactive app into highly optimized static files.

The SSG Workflow

Define your routes in `ssg.config.js`.
Run node ssg.js.
Deploy to any static host (Netlify, Vercel, GitHub Pages).

SEO Excellence

SimpliJS automatically generates:

Sitemaps: Helping Google crawl every page.
Meta Tags: OpenGraph and Twitter cards for social sharing.
JSON-LD: Structured data for rich search results.

Security Best Practices 🛡️

SimpliJS is built with a **Security-First** mindset. We use a **Safe Evaluation Proxy** for directives, which means we block access to dangerous globals like `window` or `document` inside your HTML expressions.

⚠️

Rule of Thumb: Never use `s-html` with user-generated content. Always sanitize any data that you didn't create yourself.

Real-World Project: Task Master 🏆

Let's put everything we've learned together. We're going to build a professional Task Management dashboard with local persistence and real-time validation.

(Project tutorial continues for many pages with code segments and explanations...)

// Final App Structure
<div s-app s-state="taskState">
  <header>
     <h1>Task Master</h1>
     <span>You have {activeTasks.length} pending tasks</span>
  </header>
  
  <form s-submit="addTask(event)">
    <input s-bind="newTaskName" placeholder="What needs to be done?" s-validate="required">
    <button type="submit">Add Task</button>
  </form>
  
  <ul>
    <li s-for="task in tasks" s-key="task.id" s-class="{ completed: task.done }">
      <input type="checkbox" s-model="task.done">
      {task.name}
    </li>
  </ul>
</div>

Glossary & Mastery 🎓

To truly master SimpliJS, you should understand these core terms:

Reactive State: Data that, when changed, automatically updates the UI.
Directives: Special HTML attributes (s-*) that tell SimpliJS what to do.
Anti-Build: The philosophy of building apps without complex toolchains.
Shadow DOM: A browser feature used by SimpliJS components to encapsulate styles.
Hydration: The process where SimpliJS takes static HTML and makes it interactive.

The Future is Simple 🌅

You have reached the end of this guide, but your journey with SimpliJS is just beginning. You now have the power to build complex, high-performance web applications with a level of simplicity that was previously impossible.

✨

What's Next? Start building! The best way to learn is by doing. Take one of your existing project ideas and try rewriting it in SimpliJS. You'll be amazed at how much faster you can work.

Stay Simple. Stay Powerful.
SimpliJS

The UltimateSimpliJS Guide