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 } from '@core/state.js';

State<T> interface

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:

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, 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 { trackEvents } from '@core-utils/events.js';

trackEvents() is an optional helper. Inside Deskflow, prefer this.on(target, type, handler) — it handles cleanup automatically and is the pattern all chapters teach. trackEvents is available for cases outside a controller context.

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.

Appendices

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