# No.JS Public JavaScript API Reference
The `NoJS` object is the single entry point to the framework's JavaScript API. When using the CDN (`
```
---
## NoJS.init(root?)
Initialize the framework on a root DOM element. Walks the DOM tree, activates directives, loads remote templates, and starts the router if a `[route-view]` element exists.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `root` | Element | `document.body` | The root element to process |
```javascript
// Automatic (CDN script tag) -- no call needed
//
// Manual (ESM/npm)
import NoJS from '@erickxavier/no-js';
NoJS.config({ baseApiUrl: '/api' });
NoJS.init();
// Initialize on a specific subtree
NoJS.init(document.getElementById('app'));
```
**Lifecycle**: `init()` is idempotent -- calling it more than once is a no-op. The CDN entry point calls `NoJS.init()` automatically on `DOMContentLoaded`. For ESM/CJS consumers, call it manually after configuration. Returns a `Promise` that resolves when initialization is complete (including plugin `init()` hooks).
**`NoJS._initialized`** (getter/setter): Returns `true` after `init()` has been called. Setting it to `false` resets initialization state, allowing `init()` to be called again (used primarily in tests).
**Initialization sequence**:
1. Load external locale files (blocking, if `i18n.loadPath` is set)
2. Process inline template includes (``)
3. Load remote templates (Phase 1: priority + default route)
4. Create router if `[route-view]` is present
5. `processTree(root)` -- first paint
6. Initialize router (navigate to current URL)
7. Background preload remaining route templates (Phase 2)
8. Initialize DevTools integration
9. Call `init()` on all installed plugins (in installation order)
10. Emit `plugins:ready` event
---
## NoJS.directive(name, handler)
Register a custom directive that No.JS will recognize on DOM elements.
| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | The attribute name to match (e.g., `"tooltip"` matches `
`) |
| `handler` | object | Directive definition with `priority` and `init` |
### Handler shape
```javascript
{
priority: 20, // Execution order (lower = earlier). Default priorities:
// 0 = state/store, 1 = fetch, 2 = computed,
// 5 = route/ref, 10 = structural, 20 = rendering, 30 = effects
init(el, attrName, value) { // Called once when the directive is first processed
// el - the DOM element
// attrName - the full attribute name (e.g., "tooltip")
// value - the attribute value string
}
}
```
### Examples
```javascript
// Simple tooltip directive
NoJS.directive('tooltip', {
priority: 20,
init(el, attrName, value) {
el.title = value;
el.style.cursor = 'help';
}
});
// Auto-focus directive
NoJS.directive('autofocus', {
priority: 30,
init(el) {
requestAnimationFrame(() => el.focus());
}
});
// Directive that uses the reactive context
NoJS.directive('log-click', {
priority: 20,
init(el, attrName, value) {
el.addEventListener('click', () => {
const ctx = NoJS.findContext(el);
const result = NoJS.evaluate(value, ctx);
console.log('Clicked:', result);
});
}
});
```
```html
Edit
```
### Default priority
When `priority` is omitted from a handler, it defaults to **50**.
### Wildcard patterns
Custom directives can use wildcard patterns to match attribute prefixes. The built-in patterns are `class-*`, `on:*`, `style-*`, and `bind-*`. Plugins can register additional patterns (e.g., `my-*`) to match `my-foo`, `my-bar`, etc.
### Custom directive utilities
The following internal utilities are available for custom directives (imported from framework internals or accessible on the `NoJS` object):
| Utility | Description |
|---------|-------------|
| `_onDispose(fn)` | Register a cleanup callback on the element currently being processed. Called automatically when the element is removed from the DOM. Use for intervals, observers, window listeners |
| `_watchExpr(expr, ctx, fn)` | Watch an expression for changes. Automatically subscribes to `$store` watchers if the expression references `$store`. Cleanup is registered via `_onDispose` |
| `_disposeTree(root)` | Dispose all directives on a DOM subtree (root + descendants). Clears watchers, listeners, and disposers, and sets `__declared = false` |
| `_disposeChildren(parent)` | Like `_disposeTree` but only disposes descendants, not the parent itself |
| `el.__declared = false` | Force an element to be re-processed by `processTree()` on its next pass. Useful after dynamically changing directive attributes |
---
## NoJS.filter(name, fn)
Register a custom filter for use in pipe expressions.
| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | The filter name used after `|` in expressions |
| `fn` | function | Transform function. First argument is the piped value; additional arguments follow |
```javascript
// Single-argument filter
NoJS.filter('initials', (name) => {
return name.split(' ').map(w => w[0]).join('').toUpperCase();
});
// Multi-argument filter
NoJS.filter('pad', (value, length, char) => {
return String(value).padStart(length, char || '0');
});
// Filter using external library
NoJS.filter('markdown', (text) => {
return marked.parse(text);
});
```
```html
```
---
## NoJS.validator(name, fn)
Register a custom form validation rule.
| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | The validator name used in `validate="..."` |
| `fn` | function | Receives the field value, returns `true` if valid or a string error message if invalid |
```javascript
NoJS.validator('phone', (value) => {
return /^\+?[\d\s\-()]{7,15}$/.test(value);
});
NoJS.validator('strong-password', (value) => {
if (value.length < 8) return 'Must be at least 8 characters';
if (!/[A-Z]/.test(value)) return 'Must contain an uppercase letter';
if (!/[0-9]/.test(value)) return 'Must contain a number';
return true;
});
NoJS.validator('matches', (value, fieldName) => {
// Access other field values via the second argument
return value === document.querySelector(`[name="${fieldName}"]`)?.value;
});
```
```html
```
---
## NoJS.i18n(options)
Configure internationalization. Can be called before or after `NoJS.config()`. Options are merged with any `i18n` settings from config.
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `loadPath` | string | `null` | URL pattern: `"locales/{locale}/{ns}.json"` |
| `ns` | string[] | `[]` | Namespaces to load |
| `defaultLocale` | string | `"en"` | Default locale |
| `fallbackLocale` | string | `"en"` | Fallback locale for missing keys |
| `persist` | boolean | `false` | Persist locale choice to `localStorage` (`"nojs-locale"` key) |
| `detectBrowser` | boolean | `false` | Detect locale from `navigator.language` |
| `locales` | object | -- | Inline locale definitions |
| `cache` | boolean | `true` | Cache loaded locale files |
**Locale resolution priority** (highest to lowest):
1. Persisted value from `localStorage` (when `persist: true`)
2. Browser language (when `detectBrowser: true`)
3. `defaultLocale`
### Examples
```javascript
// Inline translations
NoJS.i18n({
defaultLocale: 'en',
locales: {
en: { greeting: 'Hello', farewell: 'Goodbye' },
es: { greeting: 'Hola', farewell: 'Adios' },
pt: { greeting: 'Ola', farewell: 'Tchau' }
}
});
// External locale files
NoJS.i18n({
loadPath: '/locales/{locale}/common.json',
defaultLocale: 'en',
fallbackLocale: 'en',
detectBrowser: true,
persist: true
});
// With namespaces
NoJS.i18n({
loadPath: '/locales/{locale}/{ns}.json',
ns: ['common', 'dashboard'],
defaultLocale: 'en'
});
```
```html
```
---
## NoJS.on(event, callback)
Subscribe to the global event bus. Returns an unsubscribe function.
| Parameter | Type | Description |
|-----------|------|-------------|
| `event` | string | Event name (any string) |
| `callback` | function | Handler called with event data |
```javascript
// Subscribe
const unsub = NoJS.on('user:login', (data) => {
console.log('User logged in:', data.name);
});
// Unsubscribe when done
unsub();
```
Events can be emitted from HTML using the `trigger` directive:
```html
...
```
```javascript
// Cross-component communication
NoJS.on('theme:change', (theme) => {
document.body.className = theme;
});
```
---
## NoJS.use(plugin, options?)
Register a plugin with the framework. Plugins extend NoJS with new directives, filters, interceptors, globals, and lifecycle hooks.
| Parameter | Type | Description |
|-----------|------|-------------|
| `plugin` | object \| function | Plugin object or named install function |
| `options` | object | Optional configuration passed to the plugin's `install` function |
### Plugin interface
```javascript
{
name: 'my-plugin', // Required. Unique plugin name
version: '1.0.0', // Optional. Semver string
capabilities: ['auth'], // Optional. Informational only -- logged in debug mode, not enforced
install(NoJS, options) { // Required. Called immediately on use()
// Register directives, filters, interceptors, globals, etc.
},
init(NoJS) { // Optional. Called after NoJS.init() completes
// DOM is ready, router/stores are available
},
dispose(NoJS) { // Optional. Called during NoJS.dispose()
// Cleanup timers, event listeners, connections, etc.
}
}
```
**Directive freeze**: After core directives are registered, `_freezeDirectives()` is called. Plugins cannot override core directive names (e.g., `bind`, `state`, `if`). They can only register new, non-conflicting names.
### Function shorthand
Named functions are accepted as a shorthand (the function name becomes the plugin name):
```javascript
NoJS.use(function analytics(NoJS, options) {
NoJS.interceptor('response', (res, url) => {
track(url, res.status);
return res;
});
});
```
### Options
The optional `options` object is passed directly to the plugin's `install` function. One special key:
| Option | Type | Description |
|--------|------|-------------|
| `trusted` | boolean | Grant the plugin access to unredacted HTTP headers and URLs in interceptors. Default: `false` |
### Examples
```javascript
// Object plugin
const authPlugin = {
name: 'auth',
version: '1.0.0',
capabilities: ['interceptor', 'store'],
install(NoJS, options) {
NoJS.interceptor('request', (url, opts) => {
const token = NoJS.store.auth?.token;
if (token) {
opts.headers = opts.headers || {};
opts.headers['Authorization'] = 'Bearer ' + token;
}
return opts;
});
},
init(NoJS) {
console.log('Auth plugin ready');
},
dispose(NoJS) {
console.log('Auth plugin disposed');
}
};
NoJS.use(authPlugin);
NoJS.use(authPlugin, { trusted: true }); // Grant header access
// Duplicate installs are no-ops (same object)
NoJS.use(authPlugin); // Silently ignored
```
**Lifecycle**: `install()` runs synchronously during `use()`. If `NoJS.init()` has already completed and the plugin defines `init()`, it is called immediately (awaited). `dispose()` is called in reverse installation order during `NoJS.dispose()`.
**Constraints**: Plugin names must be unique and non-empty. Installing a different plugin object with the same name logs a warning and is rejected. Plugins cannot be installed during `dispose()`.
---
## NoJS.global(name, value)
Register a reactive global variable accessible as `$name` in all expressions.
| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Variable name (without the `$` prefix). Must start with a letter and contain only `[a-zA-Z0-9_]` |
| `value` | any | The value to expose. Objects are sanitized (prototype keys stripped). Functions, `eval`, and `Function` references are rejected |
```javascript
// Register a global
NoJS.global('apiVersion', '2.1');
NoJS.global('theme', { mode: 'dark', accent: '#0af' });
```
```html
...
```
**Reserved names**: The following names are reserved and cannot be used: `store`, `route`, `router`, `i18n`, `refs`, `form`, `parent`, `watch`, `set`, `notify`, `raw`, `isProxy`, `listeners`, `app`, `config`, `env`, `debug`, `version`, `plugins`, `globals`, `el`, `event`, `self`, `this`, `super`, `window`, `document`, `toString`, `valueOf`, `hasOwnProperty`.
**Ownership**: When called inside a plugin's `install()`, the global is tracked as owned by that plugin. Overwriting a global owned by a different plugin logs a warning.
---
## NoJS.dispose()
Tear down the entire NoJS instance. Disposes plugins in reverse installation order, clears interceptors, globals, stores, event bus, and the router.
```javascript
await NoJS.dispose();
// All plugins disposed, all state cleared
```
**Behavior**:
1. Calls `dispose()` on each installed plugin in reverse order (with a 3-second timeout per plugin)
2. Clears all plugins, globals, interceptors, stores, and event listeners
3. Destroys the router instance
4. Resets initialization state so `NoJS.init()` can be called again
Returns a `Promise` that resolves when teardown is complete.
---
## NoJS.CANCEL
Read-only `Symbol` sentinel. Return an object with this symbol key set to `true` from a request interceptor to abort the request.
```javascript
NoJS.interceptor('request', (url, opts) => {
if (isBlacklisted(url)) {
return { [NoJS.CANCEL]: true };
}
return opts;
});
```
The cancelled request throws a `DOMException` with name `"AbortError"`, which is handled by the `error` template if present.
---
## NoJS.RESPOND
Read-only `Symbol` sentinel. Return an object with this symbol key from a request interceptor to short-circuit the request and provide a mock response without hitting the network.
```javascript
NoJS.interceptor('request', (url, opts) => {
if (url.includes('/cached-data')) {
return { [NoJS.RESPOND]: { users: cachedUsers } };
}
return opts;
});
```
The value of `[NoJS.RESPOND]` becomes the parsed response data.
---
## NoJS.REPLACE
Read-only `Symbol` sentinel. Return an object with this symbol key from a response interceptor to replace the response data entirely.
```javascript
NoJS.interceptor('response', (response, url) => {
if (url.includes('/transform')) {
return { [NoJS.REPLACE]: transformedData };
}
return response;
});
```
---
## NoJS.interceptor(type, fn)
Register request or response interceptors for all HTTP directives (`get`, `post`, `put`, `patch`, `delete`). Interceptors can be synchronous or asynchronous (return a Promise).
| Parameter | Type | Description |
|-----------|------|-------------|
| `type` | `"request"` \| `"response"` | The interception point |
| `fn` | function | Interceptor function (sync or async) |
### Request interceptor
Receives `(url, options)` and must return `options` (possibly modified), or a sentinel object (`CANCEL`, `RESPOND`). The URL is read-only and cannot be reassigned.
```javascript
NoJS.interceptor('request', (url, opts) => {
// Add auth header to every request
const token = NoJS.store.auth?.token;
if (token) {
opts.headers = opts.headers || {};
opts.headers['Authorization'] = 'Bearer ' + token;
}
return opts;
});
// Async interceptor
NoJS.interceptor('request', async (url, opts) => {
const token = await refreshTokenIfNeeded();
opts.headers['Authorization'] = 'Bearer ' + token;
return opts;
});
```
### Response interceptor
Receives `(response, url)` and must return a response (possibly modified), or a sentinel object (`REPLACE`).
```javascript
NoJS.interceptor('response', (response, url) => {
if (response.status === 401) {
NoJS.store.auth.token = null;
NoJS.router.push('/login');
}
return response;
});
```
### Plugin tracking and header redaction
When interceptors are registered inside a plugin's `install()`, they are automatically tagged with the plugin name. By default, response interceptors receive a **redacted** response object with sensitive headers (`Authorization`, `Cookie`, `Set-Cookie`, etc.) and URL query parameters stripped. Plugins installed with `{ trusted: true }` receive the original unredacted response.
### Interceptor timeout
Each interceptor has a 5-second execution timeout. If an interceptor exceeds this limit, it is skipped and a warning is logged.
### Recursion depth guard
Interceptors are protected by a maximum recursion depth of **1**. If an interceptor triggers another fetch that would re-enter the interceptor chain, the nested call skips all interceptors to prevent infinite loops.
### Untrusted interceptor response
Untrusted (non-`trusted`) response interceptors receive a **frozen shell** object instead of the real `Response`. The shell exposes only: `status`, `ok`, `statusText`, `headers` (with sensitive response headers removed), and `url` (with sensitive query params redacted). This prevents untrusted plugins from accessing cookies, tokens, or raw response bodies through interceptors.
### Sensitive header redaction
**Request headers redacted** from untrusted interceptors: `authorization`, `x-api-key`, `x-auth-token`, `cookie`, `proxy-authorization`, `set-cookie`, `x-csrf-token`, plus any header matching `/^x-(auth|api)-/i`.
**Response headers redacted**: `set-cookie`, `x-csrf-token`, `x-auth-token`, `www-authenticate`, `proxy-authenticate`.
**URL query param redaction**: Parameters matching `token|key|secret|auth|password|credential` (case-insensitive) are replaced with `[REDACTED]` for untrusted interceptors.
### Retry behavior
Multiple interceptors of the same type run in registration order. Requests that fail with an `AbortError` (including cancellations via `NoJS.CANCEL`) are **never retried**, regardless of the `retries` configuration.
---
## NoJS.store
Access global reactive stores. Returns the stores object; individual stores are accessed as properties.
```javascript
// Read store data
console.log(NoJS.store.auth.user);
console.log(NoJS.store.cart.items.length);
// Mutate store data (call NoJS.notify() afterward for UI update)
NoJS.store.auth.user = { name: 'John' };
NoJS.store.cart.items.push({ id: 1, name: 'Widget' });
NoJS.notify();
```
Stores are created via `NoJS.config({ stores: { ... } })` or from HTML with the `store` directive:
```html
...
```
```html
items in cart
```
---
## NoJS.notify()
Trigger a UI update for all store watchers. Call this after mutating store data from external JavaScript (outside of No.JS expressions).
```javascript
// Mutation from external JS (e.g., WebSocket handler, third-party library)
NoJS.store.notifications.items.push({ text: 'New message', read: false });
NoJS.notify(); // UI elements bound to $store.notifications update
// Inside a WebSocket handler
socket.onmessage = (event) => {
const data = JSON.parse(event.data);
NoJS.store.messages.list.push(data);
NoJS.store.messages.unread++;
NoJS.notify();
};
```
**When to call**: Only when mutating stores from outside No.JS (plain JavaScript, WebSocket callbacks, third-party libraries). Mutations from No.JS expressions (`on:click="$store.cart.items.push(item)"`) trigger reactivity automatically.
---
## NoJS.router
Access the router instance. Only available after initialization when a `[route-view]` element exists in the DOM.
### Properties and methods
| Member | Type | Description |
|--------|------|-------------|
| `router.current` | object | Current route: `{ path, params, query, hash, matched }` |
| `router.push(path)` | async function | Navigate to a new path (adds history entry). Returns a Promise |
| `router.replace(path)` | async function | Navigate without adding a history entry. Returns a Promise |
| `router.back()` | function | Go back one history entry (`window.history.back()`) |
| `router.forward()` | function | Go forward one history entry (`window.history.forward()`) |
| `router.on(fn)` | function | Listen for route changes. Returns an unsubscribe function |
### Examples
```javascript
// Programmatic navigation
NoJS.router.push('/users/42');
NoJS.router.push('/search?q=hello');
NoJS.router.replace('/login'); // No back-button entry
// Navigation with hash
NoJS.router.push('/docs#cheatsheet');
// History navigation
NoJS.router.back();
NoJS.router.forward();
// Read current route
console.log(NoJS.router.current.path); // "/users/42"
console.log(NoJS.router.current.params); // { id: "42" }
console.log(NoJS.router.current.query); // { q: "hello" }
// Listen for route changes
const unsub = NoJS.router.on((route) => {
console.log('Navigated to:', route.path);
analytics.pageView(route.path);
});
// Stop listening
unsub();
// Register a route programmatically
NoJS.router.register('/dynamic-path', templateElement, 'outletName');
```
```html
Dashboard
```
---
## NoJS.locale
Getter/setter for the current locale. Changing the locale triggers re-rendering of all `t` (translation) bindings.
```javascript
// Get current locale
console.log(NoJS.locale); // "en"
// Set locale
NoJS.locale = 'pt';
NoJS.locale = 'es';
```
```html
```
---
## NoJS.baseApiUrl
Getter/setter for the default API base URL. This is prepended to relative URLs in fetch directives.
```javascript
// Get
console.log(NoJS.baseApiUrl); // "https://api.example.com"
// Set (e.g., switch environments)
NoJS.baseApiUrl = 'https://staging-api.example.com';
```
```html
...
...
```
URL resolution walks up the ancestor chain until it finds an element with a `base` attribute, or falls back to `NoJS.baseApiUrl`.
---
## NoJS.version
Read-only string containing the current No.JS version.
```javascript
console.log(NoJS.version); // "1.14.0"
```
```html
```
---
## Special Context Variables
These variables are available in No.JS expressions depending on the context:
### Global
| Variable | Description |
|----------|-------------|
| `$store` | Access global stores (e.g., `$store.auth.user`) |
| `$route` | Current route: `{ path, params, query, hash, matched }` |
| `$router` | Router instance: `push()`, `replace()`, `back()`, `forward()` |
| `$refs` | Named element references set via `ref="name"` |
| `$i18n` | i18n context: `locale` (get/set), `t(key, params)` |
### Events
| Variable | Where | Description |
|------------|-----------------|--------------------------------|
| `$event` | `on:*` handlers | The native DOM event object |
| `$el` | `on:*` handlers | The current element |
### Loops
| Variable | Where | Description |
|------------|--------------------|------------------------------------------|
| `$index` | `foreach`, `each`, `for` | Zero-based index of the current item |
| `$count` | `foreach`, `each`, `for` | Total number of items in the loop |
| `$first` | `foreach`, `each`, `for` | `true` if first item |
| `$last` | `foreach`, `each`, `for` | `true` if last item |
| `$even` | `foreach`, `each`, `for` | `true` if index is even |
| `$odd` | `foreach`, `each`, `for` | `true` if index is odd |
### Forms
| Variable | Where | Description |
|------------|----------------------------|--------------------------------------------------------------------------------------------|
| `$form` | Inside `