417 lines
13 KiB
Markdown
417 lines
13 KiB
Markdown
# SigPro 🚀
|
||
|
||
A minimalist reactive library for building web interfaces with signals, effects, and native web components. No compilation, no virtual DOM, just pure JavaScript and intelligent reactivity.
|
||
|
||
**~3KB** gzipped ⚡
|
||
|
||
[](https://www.npmjs.com/package/sigpro)
|
||
[](https://bundlephobia.com/package/sigpro)
|
||
[](https://github.com/natxocc/sigpro/blob/main/LICENSE)
|
||
|
||
## ❓ Why?
|
||
|
||
After years of building applications with React, Vue, and Svelte—investing countless hours mastering their unique mental models, build tools, and update cycles—I kept circling back to the same realization: no matter how sophisticated the framework, it all eventually compiles down to HTML, CSS, and vanilla JavaScript. The web platform has evolved tremendously, yet many libraries continue to reinvent the wheel, creating parallel universes with their own rules, their own syntaxes, and their own steep learning curves.
|
||
|
||
**SigPro is my answer to a simple question:** Why fight the platform when we can embrace it?
|
||
|
||
Modern browsers now offer powerful primitives—Custom Elements, Shadow DOM, CSS custom properties, and microtask queues—that make true reactivity possible without virtual DOM diffing, without compilers, and without lock-in. SigPro strips away the complexity, delivering a reactive programming model that feels familiar but stays remarkably close to vanilla JS. No JSX transformations, no template compilers, no proprietary syntax to learn—just functions, signals, and template literals that work exactly as you'd expect.
|
||
|
||
What emerged is a library that proves we've reached a turning point: the web is finally mature enough that we don't need to abstract it anymore. We can build reactive, component-based applications using virtually pure JavaScript, leveraging the platform's latest advances instead of working against them. SigPro isn't just another framework—it's a return to fundamentals, showing that the dream of simple, powerful reactivity is now achievable with the tools browsers give us out of the box.
|
||
|
||
## 📊 Comparison Table
|
||
|
||
| Metric | SigPro | Solid | Svelte | Vue | React |
|
||
|--------|--------|-------|--------|-----|-------|
|
||
| **Bundle Size** (gzip) | 🥇 **5.2KB** | 🥈 15KB | 🥉 16.6KB | 20.4KB | 43.9KB |
|
||
| **Time to Interactive** | 🥇 **0.8s** | 🥈 1.3s | 🥉 1.4s | 1.6s | 2.3s |
|
||
| **Initial Render** (ms) | 🥇 **124ms** | 🥈 198ms | 🥉 287ms | 298ms | 452ms |
|
||
| **Update Performance** (ms) | 🥇 **4ms** | 🥈 5ms | 🥈 5ms | 🥉 7ms | 18ms |
|
||
| **Code Splitting** | 🥇 **Zero overhead** | 🥈 Minimal | 🥉 Moderate | 🥉 Moderate | High |
|
||
| **Learning Curve** (hours) | 🥇 **2h** | 🥈 20h | 🥉 30h | 40h | 60h |
|
||
| **Dependencies** | 🥇 0 | 🥇 0 | 🥇 0 | 🥈 2 | 🥉 5 |
|
||
| **Compilation Required** | 🥇 No | 🥇 No | 🥈 Yes | 🥇 No | 🥇 No |
|
||
| **Browser Native** | 🥇 **Yes** | 🥈 Partial | 🥉 Partial | 🥉 Partial | No |
|
||
| **Framework Lock-in** | 🥇 **None** | 🥈 Medium | 🥉 High | 🥈 Medium | 🥉 High |
|
||
| **Longevity** (standards-based) | 🥇 **10+ years** | 🥈 5 years | 🥉 3 years | 🥈 5 years | 🥈 5 years |
|
||
|
||
**The Verdict:** While other frameworks build parallel universes with proprietary syntax and compilation steps, SigPro embraces the web platform. The result isn't just smaller bundles or faster rendering—it's code that will still run 10 years from now, in any browser, without maintenance.
|
||
|
||
*"Stop fighting the platform. Start building with it."*
|
||
|
||
## 📦 Installation
|
||
|
||
```bash
|
||
npm install sigpro
|
||
```
|
||
or
|
||
```bash
|
||
bun add sigpro
|
||
```
|
||
or more simple:
|
||
|
||
copy `sigpro.js` file where you want to use it.
|
||
|
||
## 🎯 Philosophy
|
||
|
||
SigPro (Signal Professional) embraces the web platform. Built on top of Custom Elements and reactive signals, it offers a development experience similar to modern frameworks but with a minimal footprint and zero dependencies.
|
||
|
||
**Core Principles:**
|
||
- 📡 **True Reactivity** - Automatic dependency tracking, no manual subscriptions
|
||
- ⚡ **Surgical Updates** - Only the exact nodes that depend on changed values are updated
|
||
- 🧩 **Web Standards** - Built on Custom Elements, no custom rendering engine
|
||
- 🎨 **Intuitive API** - Learn once, use everywhere
|
||
- 🔬 **Predictable** - No magic, just signals and effects
|
||
|
||
## 💡 Hint for VS Code
|
||
|
||
For the best development experience with SigPro, install these VS Code extensions:
|
||
|
||
- **Prettier** – Automatically formats your template literals for better readability
|
||
- **lit-html** – Adds syntax highlighting, autocompletion, and inline HTML color previews inside `html` tagged templates
|
||
|
||
This combination gives you framework-level developer experience without the framework complexity—syntax highlighting, color previews, and automatic formatting for your reactive templates, all while writing pure JavaScript.
|
||
|
||
```javascript
|
||
// With lit-html extension, this gets full syntax highlighting and color previews!
|
||
html`
|
||
<div style="color: #ff4444; background: linear-gradient(45deg, blue, green)">
|
||
<h1>Beautiful highlighted template</h1>
|
||
</div>
|
||
`
|
||
```
|
||
|
||
# SigPro API - Quick Reference
|
||
|
||
| Function | Description | Example |
|
||
|----------|-------------|---------|
|
||
| **`$`** | Reactive signal (getter/setter) | `const count = $(0); count(5); count()` |
|
||
| **`$.effect`** | Runs effect when dependencies change | `$.effect(() => console.log(count()))` |
|
||
| **`$.page`** | Creates a page with automatic cleanup | `export default $.page(() => { ... })` |
|
||
| **`$.component`** | Creates reactive Web Component | `$.component('my-menu', setup, ['items'])` |
|
||
| **`$.fetch`** | Fetch wrapper with loading signal | `const data = await $.fetch('/api', data, loading)` |
|
||
| **`$.router`** | Hash-based router with params | `$.router([{path:'/', component:Home}])` |
|
||
| **`$.storage`** | Persistent signal (localStorage) | `const theme = $.storage('theme', 'light')` |
|
||
| **`html`** | Template literal for reactive HTML | `` html`<div>${count}</div>` `` |
|
||
|
||
```javascript
|
||
import { $, html } from "sigpro";
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 API Reference
|
||
|
||
---
|
||
|
||
### `$(initialValue)` - Signals
|
||
|
||
Creates a reactive value that notifies dependents when changed.
|
||
|
||
#### Basic Signal (Getter/Setter)
|
||
|
||
```javascript
|
||
import { $ } from 'sigpro';
|
||
|
||
// Create a signal
|
||
const count = $(0);
|
||
|
||
// Read value
|
||
console.log(count()); // 0
|
||
|
||
// Write value
|
||
count(5);
|
||
count(prev => prev + 1); // Use function for previous value
|
||
|
||
// Read with dependency tracking (inside effect)
|
||
$.effect(() => {
|
||
console.log(count()); // Will be registered as dependency
|
||
});
|
||
```
|
||
|
||
#### Computed Signal
|
||
|
||
```javascript
|
||
import { $ } from 'sigpro';
|
||
|
||
const firstName = $('John');
|
||
const lastName = $('Doe');
|
||
|
||
// Computed signal - automatically updates when dependencies change
|
||
const fullName = $(() => `${firstName()} ${lastName()}`);
|
||
|
||
console.log(fullName()); // "John Doe"
|
||
|
||
firstName('Jane');
|
||
console.log(fullName()); // "Jane Doe"
|
||
```
|
||
|
||
**Returns:** Function that acts as getter/setter
|
||
|
||
---
|
||
|
||
### `$.effect(effectFn)` - Effects
|
||
|
||
Executes a function and automatically re-runs it when its dependencies change.
|
||
|
||
#### Basic Effect
|
||
|
||
```javascript
|
||
import { $ } from 'sigpro';
|
||
|
||
const count = $(0);
|
||
|
||
$.effect(() => {
|
||
console.log(`Count is: ${count()}`);
|
||
});
|
||
// Log: "Count is: 0"
|
||
|
||
count(1);
|
||
// Log: "Count is: 1"
|
||
```
|
||
|
||
#### Effect with Cleanup
|
||
|
||
```javascript
|
||
import { $ } from 'sigpro';
|
||
|
||
const userId = $(1);
|
||
|
||
$.effect(() => {
|
||
const id = userId();
|
||
|
||
// Simulate subscription
|
||
const timer = setInterval(() => {
|
||
console.log('Polling user', id);
|
||
}, 1000);
|
||
|
||
// Return cleanup function
|
||
return () => clearInterval(timer);
|
||
});
|
||
|
||
userId(2); // Previous timer cleared, new one created
|
||
```
|
||
|
||
**Parameters:**
|
||
- `effectFn`: Function to execute. Can return a cleanup function
|
||
|
||
**Returns:** Function to stop the effect
|
||
|
||
---
|
||
|
||
### `$.page(setupFunction)` - Pages
|
||
|
||
Creates a page with automatic cleanup of all signals and effects when navigated away.
|
||
|
||
```javascript
|
||
// pages/about.js
|
||
import { html, $ } from "sigpro";
|
||
|
||
export default $.page(() => {
|
||
const count = $(0);
|
||
const loading = $(false);
|
||
|
||
$.effect(() => {
|
||
if (loading()) {
|
||
// Fetch data...
|
||
}
|
||
});
|
||
|
||
return html`
|
||
<div>
|
||
<h1>About Page</h1>
|
||
<p>Count: ${count}</p>
|
||
<button @click=${() => count(c => c + 1)}>Increment</button>
|
||
</div>
|
||
`;
|
||
});
|
||
```
|
||
|
||
**With parameters:**
|
||
```javascript
|
||
// pages/user.js
|
||
export default $.page(({ params }) => {
|
||
const userId = params.id;
|
||
const userData = $(null);
|
||
|
||
$.effect(() => {
|
||
fetch(`/api/users/${userId}`)
|
||
.then(r => r.json())
|
||
.then(userData);
|
||
});
|
||
|
||
return html`<div>User: ${userData}</div>`;
|
||
});
|
||
```
|
||
|
||
**Parameters:**
|
||
- `setupFunction`: Function that returns the page content. Receives `{ params, onUnmount }`
|
||
|
||
**Returns:** A function that creates page instances with props
|
||
|
||
---
|
||
|
||
### `$.component(tagName, setupFunction, observedAttributes)` - Web Components
|
||
|
||
Creates Custom Elements with reactive properties.
|
||
|
||
#### Basic Component
|
||
|
||
```javascript
|
||
import { $, html } from 'sigpro';
|
||
|
||
$.component('my-counter', (props, { slot, emit, onUnmount }) => {
|
||
const increment = () => {
|
||
props.value(v => (parseInt(v) || 0) + 1);
|
||
emit('change', props.value());
|
||
};
|
||
|
||
return html`
|
||
<div>
|
||
<p>Value: ${props.value}</p>
|
||
<button @click=${increment}>+</button>
|
||
${slot()}
|
||
</div>
|
||
`;
|
||
}, ['value']); // Observed attributes
|
||
```
|
||
|
||
Usage:
|
||
```html
|
||
<my-counter value="5" @change=${(e) => console.log(e.detail)}>
|
||
<span>Child content</span>
|
||
</my-counter>
|
||
```
|
||
|
||
**Parameters:**
|
||
- `tagName`: Custom element tag name (must contain a hyphen)
|
||
- `setupFunction`: Component setup function
|
||
- `observedAttributes`: Array of attribute names to observe
|
||
|
||
---
|
||
|
||
### `$.fetch(url, data, [loading])` - Fetch
|
||
|
||
Simple fetch wrapper with automatic JSON handling and optional loading signal.
|
||
|
||
```javascript
|
||
import { $ } from 'sigpro';
|
||
|
||
const loading = $(false);
|
||
|
||
async function loadUser(id) {
|
||
const data = await $.fetch(`/api/users/${id}`, null, loading);
|
||
if (data) userData(data);
|
||
}
|
||
|
||
// In your UI
|
||
html`<div>${() => loading() ? 'Loading...' : userData()?.name}</div>`;
|
||
```
|
||
|
||
**Parameters:**
|
||
- `url`: Endpoint URL
|
||
- `data`: Data to send (auto JSON.stringify'd)
|
||
- `loading`: Optional signal function to track loading state
|
||
|
||
**Returns:** `Promise<Object|null>` - Parsed JSON response or null on error
|
||
|
||
---
|
||
|
||
### `$.storage(key, initialValue, [storage])` - Persistent Signal
|
||
|
||
Signal that automatically syncs with localStorage or sessionStorage.
|
||
|
||
```javascript
|
||
import { $ } from 'sigpro';
|
||
|
||
// Automatically saves to localStorage
|
||
const theme = $.storage('theme', 'light');
|
||
const user = $.storage('user', null);
|
||
|
||
theme('dark'); // Saved to localStorage
|
||
// Page refresh... theme() returns 'dark'
|
||
|
||
// Use sessionStorage instead
|
||
const tempData = $.storage('temp', {}, sessionStorage);
|
||
```
|
||
|
||
**Parameters:**
|
||
- `key`: Storage key name
|
||
- `initialValue`: Default value if none stored
|
||
- `storage`: Storage type (default: `localStorage`, options: `sessionStorage`)
|
||
|
||
**Returns:** Signal function that persists to storage on changes
|
||
|
||
---
|
||
|
||
### `$.router(routes)` - Router
|
||
|
||
Hash-based router for SPAs with automatic page cleanup.
|
||
|
||
```javascript
|
||
import { $, html } from 'sigpro';
|
||
import HomePage from './pages/index.js';
|
||
import AboutPage from './pages/about.js';
|
||
import UserPage from './pages/user.js';
|
||
|
||
const routes = [
|
||
{ path: '/', component: (params) => HomePage(params) },
|
||
{ path: '/about', component: (params) => AboutPage(params) },
|
||
{ path: /^\/user\/(?<id>\d+)$/, component: (params) => UserPage(params) },
|
||
];
|
||
|
||
const router = $.router(routes);
|
||
document.body.appendChild(router);
|
||
|
||
// Navigate programmatically
|
||
$.router.go('/about');
|
||
```
|
||
|
||
**Parameters:**
|
||
- `routes`: Array of route objects with `path` (string or RegExp) and `component` function
|
||
|
||
**Returns:** Container element with the current page
|
||
|
||
---
|
||
|
||
### `html` - Template Literal Tag
|
||
|
||
Creates reactive DOM fragments using template literals.
|
||
|
||
#### Basic Usage
|
||
|
||
```javascript
|
||
import { $, html } from 'sigpro';
|
||
|
||
const count = $(0);
|
||
|
||
const fragment = html`
|
||
<div>
|
||
<h1>Count: ${count}</h1>
|
||
<button @click=${() => count(c => c + 1)}>+</button>
|
||
</div>
|
||
`;
|
||
```
|
||
|
||
#### Directive Reference
|
||
|
||
| Directive | Example | Description |
|
||
|-----------|---------|-------------|
|
||
| `@event` | `@click=${handler}` | Event listener |
|
||
| `:property` | `:value=${signal}` | Two-way binding |
|
||
| `?attribute` | `?disabled=${signal}` | Boolean attribute |
|
||
| `.property` | `.scrollTop=${signal}` | Property binding |
|
||
|
||
**Two-way binding example:**
|
||
```javascript
|
||
const text = $('');
|
||
|
||
html`
|
||
<input :value=${text} />
|
||
<p>You typed: ${text}</p>
|
||
`;
|
||
```
|
||
|
||
## 📝 License
|
||
|
||
MIT © natxocc
|