this.selected = event.target.value} />
```
✅ **CORRECT** - Use `{ event }` destructuring if you need the event:
```jsx
// ✅ CORRECT - Nullstack passes event as an object property
this.selected = event.target.value} />
```
✅ **BEST** - Use two-way binding with `bind` (no event handling needed):
```jsx
// ✅ BEST - Use bind for simple input binding
```
**Head Management** - You can inject content into the `` tag using a `renderHead()` method:
```jsx
class Application extends Nullstack {
renderHead() {
return (
{/* Self-closing component renders the head content */}
` is a self-closing component that renders the content from `renderHead()`. This is useful for managing meta tags, fonts, scripts, and other head elements.
#### Routing and Navigation
**Routes** - Any element can receive a `route` attribute:
```jsx
` tags with `href` starting with `/`:
```jsx
About
```
On client-side, links push history without reloading. External links (not starting with `/`) work normally.
**Special link attributes**:
- `path` - Changes path keeping query params: `About `
- `params` - Updates params keeping path: `First Page `
- Both can be combined: `Books `
**Dynamic segments** - Use `:param` syntax:
```jsx
router.path = '/dashboard'}>
Navigate
);
}
// ✅ CORRECT - Access router in any method
async someMethod({ router, instances }) {
await this.doSomething();
router.path = '/success'; // Navigate after async operation
}
}
```
**Key Rules for Navigation:**
- Always extract `router` from the method's object parameter
- Use `router.path = '/path'` for SPA navigation (no page reload)
- Use `router.url = 'url'` only for external URLs (triggers full reload)
- Never use `window.location.href` for internal navigation
**Params context** - Query string parameters:
```jsx
// URL: /books?expanded=true&page=2
initiate({ params }) {
params.expanded; // true (boolean)
params.page; // "2" (string)
// Update params (triggers redirect)
params.page = 3;
params.filter = ''; // Empty string removes param
}
```
**Route instances** - By default, components with routes use the current URL as key and reinstantiate on param changes. Override with custom `key`:
```jsx
{formattedDate}: ${total}
;
}
}
export default MyComponent;
```
**Key Rule:** If a function doesn't use Nullstack context (`instances`, `router`, `params`, etc.), it should **NOT** be a class method. Define it as a regular function outside the class.
Context properties available in methods:
- `instances` - Access to all mounted instances (client-side)
- `router` - Routing information (client-side)
- `params` - Route parameters
- `page` - Page metadata (title, description, etc.)
- `environment` - Environment flags (client, server, development, production)
- `project` - Project configuration
- `worker` - Service worker integration
- `settings` - Application settings
**IMPORTANT - Accessing Context in Methods:**
Nullstack methods receive context as a destructured object parameter. You must explicitly extract what you need:
```jsx
class MyComponent extends Nullstack {
// ❌ WRONG - No parameter destructuring
async handleSubmit() {
// router is not accessible!
router.path = '/success'; // Error: router is not defined
}
// ✅ CORRECT - Destructure context to access router, instances, etc.
async handleSubmit({ router, instances }) {
// Now router and instances are accessible
await this.saveData();
instances.app.showSuccess({ message: 'Saved!' });
router.path = '/success';
}
// ✅ CORRECT - Access multiple context properties
async loadData({ params, instances, router }) {
const id = params.id; // From URL params
const data = await this.fetchData(id);
if (!data) {
instances.app.showError({ message: 'Not found' });
router.path = '/404';
return;
}
this.data = data;
}
// ✅ CORRECT - In render, extract what you need
render({ router, instances, params }) {
return (
{params.title}
router.path = '/back'}>Back
{instances.auth.user?.name}
);
}
}
```
**Key Rules for Methods:**
- **ALWAYS use named parameters (object destructuring)** for ALL methods: `methodName({ router, instances, params })`
- Extract only what you need from the context object
- Context is **automatically injected by Nullstack** into ALL methods - never manually pass `instances`, `router`, etc.
- When calling methods, pass only custom parameters: `this.loadData({ id: 5 })` - context is injected automatically
- Context is available in **all** methods: `render`, `hydrate`, `initiate`, `prepare`, and custom methods
- Instance methods defined in Instance classes also receive context automatically: `myMethod({ router, instances })`
**Examples of Automatic Context Injection:**
```jsx
class MyComponent extends Nullstack {
// ❌ WRONG - Manually passing instances
async handleClick({ instances }) {
await this.saveData({ instances }); // DON'T DO THIS
}
async saveData({ instances }) {
instances.app.showSuccess({ message: 'Saved!' });
}
// ✅ CORRECT - Context injected automatically
async handleClick() {
await this.saveData({ id: 5 }); // Only pass custom params
}
async saveData({ id, instances }) { // instances automatically available
const data = await this.fetchData(id);
instances.app.showSuccess({ message: 'Saved!' });
}
// ✅ CORRECT - Calling instance methods
async handleSubmit({ instances }) {
// Nullstack automatically injects context into instance methods
await instances.data.loadCompanies({ admin: false }); // Only pass custom params
}
// ✅ CORRECT - Instance method receives context automatically
async loadCompanies({ admin, instances }) { // Both custom param and context available
const endpoint = admin ? sdk.api.admin.companies : sdk.api.companies;
await endpoint.get();
}
}
```
**Key Takeaway:** Nullstack automatically injects context (`instances`, `router`, `params`, etc.) into every method call. You only need to pass custom parameters.
#### Instances (Shared State & Logic)
Nullstack supports **instances** for managing shared state and logic across components (similar to React Context):
```jsx
// Define an instance component (holds state and methods)
class MyInstance extends Nullstack {
myStateHere = 'value';
myMethodHere() {
console.log(this.myStateHere);
}
myOtherMethodHere() {
this.myStateHere += ' updated';
}
}
// Mount instance in Application with a key and persistent flag
class Application extends Nullstack {
render() {
return (
);
}
}
// Access instance from any component or method via { instances }
class Home extends Nullstack {
// Available in render methods
render({ instances }) {
return (
Home
myMethodHere
myOtherMethodHere
);
}
// Also available in all other methods
async someMethod({ instances }) {
instances.hey.myMethodHere();
}
}
```
**Key points:**
- Instances are mounted with a `key` prop in the Application component
- Use `persistent` flag to keep instance alive across route changes
- Access instances via the `instances` context property (available in **all methods**)
- Instances can hold state and methods accessible from any component
- Without `persistent`, instances are destroyed when routes change
**Calling Instance Methods:**
Instance methods also receive context parameters. When calling them, Nullstack automatically passes the context:
```jsx
// Instance definition
class AuthInstance extends Nullstack {
user = null;
// Method receives context
async login({ provider, router }) {
// Login logic
this.user = await authenticate(provider);
router.path = '/dashboard';
}
async logout({ router, instances }) {
this.user = null;
instances.data.reset(); // Clear data cache
router.path = '/login';
}
}
// Using the instance
class LoginPage extends Nullstack {
async handleLogin({ instances }) {
// ✅ Call instance method - Nullstack passes context automatically
await instances.auth.login({ provider: 'google' });
}
render({ instances }) {
return (
{/* ✅ Direct reference - Works when method doesn't need custom params */}
Logout
{/* ✅ Arrow function call - Pass custom params */}
instances.auth.login({ provider: 'github' })}>
Login with GitHub
{/* ✅ Call from component method */}
Login
);
}
}
```
**Important:**
- Instance methods automatically receive the full context
- **Direct reference**: `onclick={instances.auth.logout}` works when no custom params needed
- **With custom params**: Use arrow function `onclick={() => instances.auth.login({ provider: 'google' })}`
- Custom parameters are merged with the context by Nullstack
- Access both custom params and context: `login({ provider, router, instances })`
- The `instances` object is **ALWAYS available** in every method - it's automatically injected by Nullstack
- You never need to check if `instances` exists (no need for `instances?.app`)
- Simply access instances directly: `instances.app.showError()`, `instances.data.loadCompanies()`, etc.
**Best Practice - Instances Component Pattern:**
For better organization, create a dedicated `Instances` component that houses all your instance components:
```jsx
// src/Instances.jsx
import Nullstack from 'nullstack';
import AuthInstance from './instances/AuthInstance';
import CartInstance from './instances/CartInstance';
import NotificationInstance from './instances/NotificationInstance';
class Instances extends Nullstack {
render() {
return (
<>
);
}
}
export default Application;
```
**Benefits:**
- Centralized instance management
- Cleaner Application.jsx
- Easy to see all shared state/logic at a glance
- Simpler to add/remove instances
#### SEO and Page Metadata
Use the `page` context in the `prepare()` method to set SEO metadata:
```jsx
class Home extends Nullstack {
prepare({ page, environment }) {
page.title = 'Home - My App';
page.description = 'Welcome to my application';
page.locale = 'en-US';
// Use environment to conditionally set metadata
if (environment.server) {
// Server-side only logic
page.image = '/og-image.jpg';
}
}
render() {
return Home ;
}
}
```
**Available page properties:**
- `page.title` - Page title (shows in browser tab and SEO)
- `page.description` - Meta description for SEO
- `page.locale` - Language/locale (e.g., 'en-US', 'pt-BR')
- `page.image` - Open Graph image for social media sharing
#### Server vs Client Execution
- **Server functions** - Mark with `static async`:
```jsx
static async getUsers() {
// Runs only on server, can access databases, APIs with secrets, etc.
return await database.users.findMany();
}
```
- **Client methods** - Regular instance methods run on client
- **`prepare()`** - Runs on server for SSR/SSG
- **`initiate()` / `hydrate()`** - Run on client only
#### Build Modes
Set the build mode in your `package.json` build script using the `--mode` flag:
```json
{
"scripts": {
"build": "npx nullstack build --mode=ssg",
"build:ssr": "npx nullstack build --mode=ssr"
}
}
```
- **`ssg`** - Static Site Generation (pre-renders all pages at build time)
- **`ssr`** - Server-Side Rendering (renders pages on request)