Philosophy - cynchro/OldSchoolFrontFrame GitHub Wiki

Philosophy

"We don't abstract the web. We organize it."

OLS is built around a single constraint: a developer should be able to understand any part of the framework by reading the code, without reading documentation first.

If the answer to that question is no, the feature doesn't get added.

What this means in practice

No magic

There is no hidden wiring, no auto-registration, no convention-over-configuration that requires memorization. Every import is explicit. Every dependency is visible. If you don't know how something works, you can open the file and read it — the entire framework is under 1000 lines.

No build step

ES modules run natively in modern browsers. OLS doesn't require Webpack, Vite, Rollup, Babel, or TypeScript compilation. Open a file, change it, refresh the page. That's it.

Reactive state, not reactive components

OLS has reactive state (change ctx.state.x, DOM updates) but it does not have a virtual DOM or component tree diffing. DOM updates are direct and scoped to the exact elements that depend on a changed state path. There is no reconciliation overhead.

Explicit over implicit

// Bad (implicit — where does loadData come from?)
mounted() {
  this.loadData();
}

// Good (explicit — the import is visible at the top of the file)
import { getClientes } from './services/clientes.service.js';

mounted(ctx) {
  getClientes().then(data => ctx.state.clientes = data);
}

Services own data, modules own UI state

Modules know about the DOM. Services know about APIs. Neither crosses the line. This separation makes services testable in isolation and keeps modules focused on presentation logic.

One module per route, always

The file system is the architecture. modules/clientes/ is the clientes page. There is no ambiguity about where to find the code for a given route.

The line we won't cross

Features that have been considered and rejected:

Feature Why not
TypeScript Adds a build step; types in JSDoc cover the important cases
Virtual DOM Unnecessary overhead; direct DOM updates are fast enough
Component auto-discovery Implicit magic; explicit imports are clearer
SSR / hydration Out of scope for the zero-build, static-hosting target
Plugin system Complexity for edge cases; the source is forkable
Two-way store binding Encourages over-sharing state; prefer module state

Who this is for

OLS was designed for:

  • Backend developers who need a working frontend without learning a full framework
  • Teams building internal tools where debuggability matters more than ecosystem size
  • Developers who are tired of 400MB node_modules for a CRUD app
  • Projects where the next developer reading the code might not know React, Vue, or Angular

Who this is NOT for

  • Teams building very large SPAs with hundreds of routes and complex real-time interactions
  • Projects that require SSR for SEO
  • Teams that need TypeScript at the framework core
  • Developers who want a large ecosystem of community components

Further reading