Chapter 26 — API Quick Reference

All entries verified against packages/create-nativecore/template/.nativecore/ and packages/nativecorejs/. When in doubt, open the source file — it is the canonical truth.

CoreController (@core/controller.js)

import { CoreController } from '@core/controller.js';

Factory pattern (required)

export function myController(_params, _state, _loaderData, rootElement) {
    const ctrl = new MyController(rootElement);
    return () => ctrl.destroy();
}

The factory is what lazyController calls. It must return a cleanup function.

CoreComponent (@core/component.js)

import { CoreComponent, defineComponent } from '@core/component.js';

Shadow DOM access

// Read from shadow inside onMount:
const inner = this.shadowRoot.querySelector('.inner');
// Refs are wired to this.refName directly — no manual querySelector for ref="…"

State (@core/state.js)

import { useState, computed, effect, batch, untrack, peek } from '@core/state.js';

State<T> interface

this.state / this.compute / this.effect on controllers and components use this same engine. Instance compute/effect pass { pageCleanup: false } and dispose on destroy() / disconnect.

Reconcile (@core-utils/reconcile.js)

import { reconcile } from '@core-utils/reconcile.js';

reconcile(container, items, item => item.id, item => {
    const li = document.createElement('li');
    li.textContent = item.label;
    return li;
}, (el, item) => { el.textContent = item.label; });

Keyed list: reuse nodes for the same key, move to match order, remove leftovers. create runs only for new keys. Optional update patches reused nodes. Keys are stored on data-nc-key. After inserting nodes with ref attributes, call this.rebind(container).

Context (@core/context.js)

import { createContext, provide, inject } from '@core/context.js';

const Theme = createContext('theme');
const stop = provide(host, Theme, themeState); // State or static value
const value = inject(child, Theme);
const unsub = inject(child, Theme, next => { /* subscribe */ });

Web Components context-request protocol (composed, bubbles through Shadow DOM). Use for theme, locale, or the current user — not as a global store.

Resource (@core/resource.js)

import { resource } from '@core/resource.js';

const box = resource(async (id, signal) => {
    const res = await fetch(`/api/items/${id}`, { signal });
    return res.json();
}, { source: itemId });

box.data.value;
box.loading.value;
box.error.value;
await box.refetch();

Aborts the in-flight request when source changes, on refetch(), and on page navigation (pageCleanup defaults to true).

Router (@core/router.js)

import { router } from '@core/router.js';   // internal — use via app.js
// Public surface in userland:
window.router.navigate('/tasks');
window.router.replace('/tasks');
window.router.back();
window.router.getCurrentRoute();

Registration (inside registerRoutes(r))

r.register(path, htmlFile, controller?, options?)
// returns r — chain .cache(...) on the route just registered

ControllerFunction:

(params: Record<string, string>, state?: any, loaderData?: unknown)
  => (() => void) | void | Promise<(() => void) | void>

Always return cleanup from factories: () => ctrl.destroy().

options / RouteConfig fields:

Failed loads dispatch nativecore:route-error on window (ROUTE_ERROR_EVENT). Listen for a custom error UI; the router still shows its 404 fallback. The event is for the failed page load, not each layout frame.

Path syntax

Full router API (internal — use in app.js)

window.router (frozen subset): navigate, replace, back, getCurrentRoute only. Do not rely on any other property of window.router being present — it is a frozen proxy, not the full router. Advanced APIs (prefetch, bustCache, getPathsForMiddleware, …) live on window.__NC_ROUTER__ or import router from '@core/router.js'.

Lazy controller (@core/lazyController.js)

import { createLazyController } from '@core/lazyController.js';

const lazyController = createLazyController(import.meta.url);

// Usage in registerRoutes:
r.register('/tasks', 'src/views/public/tasks.html',
    lazyController('tasksController', '../controllers/tasks.controller.js'));

• First argument: the exported function name in the controller module
• Second argument: path relative to routes.js (not to app.js)

Middleware (@core/createMiddleware.js)

import { createMiddleware } from '@core/createMiddleware.js';

const sessionMiddleware = createMiddleware('session', async (route, state) => {
    // Return true to allow navigation; false (or a redirect) to block
    return Boolean(localStorage.getItem('session'));
});

router.use(sessionMiddleware);

fn(route, state?) → boolean | Promise<boolean>

HTTP client (@core/http.js)

import http from '@core/http.js';

const data = await http.get('/api/tasks');
await http.post('/api/tasks', { title: 'New task' });
await http.put('/api/tasks/1', { done: true });
await http.patch('/api/tasks/1', { done: true });
await http.delete('/api/tasks/1');

This is the low-level HTTP primitive. For caching, tag invalidation, and the full service layer used by Deskflow, use src/services/api.service.js instead.

Services (src/services/)

api.service

import api from '@services/api.service.js';

api.setBaseURL('https://api.example.com');
await api.get('/tasks');
await api.post('/tasks', body);
await api.put('/tasks/1', body);
await api.patch('/tasks/1', body);
await api.delete('/tasks/1');
await api.getCached('/tasks', { ttl: 60 });
api.invalidateTags(['tasks']);
api.invalidateQuery(['tasks', 'list']);   // query key array, not a path string
api.clearCache();

storage.service

import storage from '@services/storage.service.js';

storage.setStrategy('local');    // 'memory' | 'session' | 'local'
storage.set('key', value);
storage.get('key');
storage.remove('key');
storage.clear();

logger.service

import logger from '@services/logger.service.js';

logger.debug('msg', data);
logger.info('msg', data);
logger.warn('msg', data);
logger.error('msg', data);

Stores (src/stores/)

Built-in stores

Generated stores (make:store)

npm.cmd run make:store -- task
# → src/stores/task.store.js
# Exports: taskItems, taskLoading, taskError, taskCount (computed),
#          loadTasks, addTask, removeTask

Path aliases (all projects)

Always include the .js extension when importing through aliases.

Realtime helpers

WebSocket (@core/ws.js)

import { connectWebSocket } from '@core/ws.js';

const socket = connectWebSocket(url, handlers, options);
socket.send(data);
socket.close();
socket.readyState;   // mirrors WebSocket.readyState
socket.isOpen;       // boolean

Handlers: onOpen, onClose, onError, onMessage (raw), onJsonMessage (when parseJson: true), onReconnect(attempt), onReconnectFailed(lastEvent).

Options: protocols, parseJson, reconnect: { maxRetries, baseDelay, maxDelay } | false, heartbeat: { interval, message? }, signal.

SSE (@core/sse.js)

import { connectSSE } from '@core/sse.js';

const disconnect = connectSSE(url, handlers, options);
disconnect();

Handlers: onOpen, onMessage (default event, raw string), onJsonMessage (when parseJson: true), onError, events: { eventName: fn }, eventsJson: { eventName: fn }, onReconnect(attempt), onReconnectFailed.

Options: parseJson, withCredentials, reconnect: { maxRetries, baseDelay, maxDelay } | false, signal.

i18n (@core/i18n.js)

import { configureI18n, i18n, t } from '@core/i18n.js';

Testing (@testing/index.js)

import { mountComponent, mountController, navigateAndWait, waitFor, fireEvent } from '@testing/index.js';

CLI scripts

Generators

npm.cmd run make:component -- <name> [--defaults] [--with-tests]
npm.cmd run make:core-component -- <name> [--defaults]
npm.cmd run make:controller -- <name> [--defaults]
npm.cmd run make:store -- <name>
npm.cmd run make:view -- <name> [--defaults]
npm.cmd run make:page -- <name> [--defaults]
npm.cmd run make:middleware -- <name>

Removers

npm.cmd run remove:component -- <name>
npm.cmd run remove:core-component -- <name>
npm.cmd run remove:view -- <name> [--yes]
npm.cmd run remove:store -- <name>
npm.cmd run remove:middleware -- <name>

Build and test

Capacitor

Events utility (@core-utils/events.js)

import { on, delegate, trackEvents, onClick, onKeydown, onFocus } from '@core-utils/events.js';

Prefer this.on(target, type, handler) inside controllers. Standalone helpers return a disposer. Shorthands: onClick, onChange, onInput, onSubmit, onKeydown, onKeyup, onFocus, onBlur, onFocusin, onFocusout, onScroll, onMouseenter, onMouseleave, onDblclick.

DOM utilities (@core-utils/dom.js)

import { dom } from '@core-utils/dom.js';

Flat maps are HTML attributes. Objects, arrays, and IDL booleans belong in props. Do not attach listeners in create().

const frame = dom.create('iframe', {
    attrs: { title: 'Preview', allowfullscreen: '' },
    props: { src: url, allowFullscreen: true },
});
dom.setProps(player, { questions, open: true });

Persist and timing

import { persistState } from '@core-utils/persist.js';
import { debounce } from '@core-utils/timing.js';

throttle / rafThrottle remain on @core/gpu-animation.js.

Observe and portal

import { clickOutside, mediaQuery, observe } from '@core-utils/observe.js';
import { portal } from '@core-utils/portal.js';

Forms (@core/form.js)

import { useForm, useFieldArray } from '@core/form.js';
import { required, email } from '@core/validators.js';

handleSubmit is a factory: await form.handleSubmit(onSave)().

Accessibility (@core-utils/a11y.js)

import { lockBodyScroll } from '@core-utils/a11y.js';

lockBodyScroll() is reference-counted and restores overflow + scrollbar compensation. Also exported from nativecorejs and nativecorejs/a11y.

Package-only APIs (not in scaffold core)

These symbols are exported by the nativecorejs npm package when you import from it directly. They are not available through the .nativecore/core/ vendored copy inside a scaffolded app.

See Appendix B — Package vs Scaffold for the full breakdown.

nc-animation (path-picking component)

You choose a preset name. The component chooses CSS compositor, Web Animations API (GPU transform / opacity), or a canvas particle overlay — whichever is cheapest for that preset. See Chapter 13.

Triggers: mount \| visible \| hover \| click \| manual. Methods: play(), pause() (WAAPI only), cancel(). Events: start, finish, cancel.

Appendices

• Appendix A — Framework comparison
• Appendix B — Package vs scaffold