Fundamentals

Fundamentals

Define a contract, write its handlers, and make your first client call.

hulla-tabs[data-docs-area-tabs] [data-slot='tabs-list'] { display: none; } /* Match the layer of Tailwind's important [hidden] rule. */ @layer base { hulla-tabs[data-docs-area-tabs][data-initial-value='documentation'] [data-slot='tabs-content'][data-value='documentation'], hulla-tabs[data-docs-area-tabs][data-initial-value='guides'] [data-slot='tabs-content'][data-value='guides'], hulla-tabs[data-docs-area-tabs][data-initial-value='reference'] [data-slot='tabs-content'][data-value='reference'], hulla-tabs[data-package-manager-tabs] [data-slot='tabs-content'][data-value='bun'] { display: block !important; } }

Browse documentation

On this page

Documentation

Switch package

Choose a package to open its documentation.

@hulla/apiBeta

Catch broken API calls when you change the contract.

Declare methods, inputs, and response statuses in a shared contract. TypeScript checks the handlers and callers against it, whether you use Fetch, Express, Hono, or an in-process call.

Editable

import { defineContract, route, response } from '@hulla/api'

export const contract = defineContract({
  routes: {
    profile: route.get('/profile', {
      responses: {
        200: response.json<{ name: string }>(),
      },
    }),
  },
})

import { defineServer } from '@hulla/api/server'
import { contract } from './contract'

export const server = defineServer(contract).implement({
  profile: ({ response }) =>
    response(200, { name: 'Ada Lovelace' }),
})

import type { Client } from '@hulla/api/client'
import { contract } from './contract'

export async function profileTitle(api: Client<typeof contract>) {
  const result = await api.profile()
  if (result.status === 200) {
    return result.body.name.toUpperCase()
  }
}

TypeScript · Ready

Real TypeScript and @hulla/api declarations. Code is type-checked locally; no API request or AI agent runs.

Edit the contract, server, or caller in the code editor. A real TypeScript worker checks every change; shortcuts can load a breaking or repaired project.

Useful for: APIs shared by web apps, services, and desktop processes.

@hulla/gittar

One template repository. As many editable starters as you need.

Download a repository snapshot and copy just the folder your tool needs. Keep the cache separate from editable files, and choose when to reuse it or check the remote.

download.options.json

Editable

{
  "subpath": "web",
  "update": "never",
  "outDir": "./project-1"
}

Cache: 0 simulated downloads · full web/ + api/ snapshot

Copy a starter, change its title, then use a new destination. The next copy starts from the unchanged cache.

Local filesystem model; no downloads or files written. Reusing a destination replaces that copy, as a real copy operation would.

Edit the download options, copy a starter, and customize it. Use another destination to copy from the untouched template cache.

Useful for: Starter generators, template catalogs, and build scripts.

@hulla/control

Catch a bad deployment config before the next step runs.

Return ok(data) or err(problem) for expected failures. Narrow the branch, transform its payload, or match both outcomes; the success and error types stay visible to the caller.

deploy.json

Editable

{
  "replicas": 3
}

Deployment pipeline

1. Parse JSONOk
2. Validate configOk
3. Build deployment planOk

3 replicas ready for deployment

Runs @hulla/control locally. Thrown syntax errors and explicit validation failures both become results. Nothing is deployed.

Break the JSON or supply an invalid replica count. Both become typed failures; later work stays unreached.

Useful for: Missing records, invalid input, and recoverable application errors.

@hulla/style

One styling pipeline. Every variant and override follows it.

An override should follow the same rules inside a variant and at the component boundary. Create cn() and vn() from one processor, compose independent variants, and infer props from their keys. One policy across your codebase.

style.ts

Editable

import { style } from '@hulla/style'
import { cn as mergeClasses } from 'cn'

const { cn, vn } = style({ composer: mergeClasses })

const $tone = vn({
  accent: 'text-primary-text',
  muted: 'text-muted-foreground',
})
const $space = vn({ compact: ['px-2', 'px-4'] })

export const compose = (extra = '') =>
  cn('py-2', $tone('accent'), $space('compact'), extra)

export const preview = {
  notice: compose(),
  activity: compose('font-semibold'),
  cell: compose('px-6'),
}

export const trace = {
  variant: $space('compact'),
  override: compose('px-6'),
}

Live preview

Up to date

Notice

Your deployment is ready.

Activity

Production updated by Ada

Table cell · local px-6 override

Release v2.0 · healthy

variantpx-4

overridepy-2 text-primary-text px-6

Uses the installed @hulla/style package and this site’s CSS.

Edit the actual style module. Preview three consumers, inspect composition output, and measure 10,000 calls to your compose() function.

Useful for: Typed size, tone, and state props in any component framework.

@hulla/dbPrivate

Update PostgreSQL. Let subscribed views update with it.

Use a typed SDK on the server and declared queries in the browser. After a write commits, affected queries rerun and publish their results. Keep your PostgreSQL database, framework, and auth provider.

Databaseproducts table

Servervalidate · commit · publish

Clientsubscribed storefront

products

Edit a name or stock level directly.

name	stock

Committed revision 0

Storefront

Rename a product, or buy one to change stock.

5 available

2 available

Sold out

Subscribed to products.list · revision 0

Try setting the first row’s stock to 10, then buy one in the storefront.

Local model with separate client and database state connected by message ports. No PostgreSQL connection.

Edit the database table or the client storefront. Writes pass through a server model, commit, and publish to a separate subscribed view.

Useful for: Dashboards and collaborative views backed by your own PostgreSQL.

hulla CLIBeta

Need to change the component? Open the source in your app.

Choose a registry and a framework, then copy the component and its support files into your app. Review the diff, customize the source, and manage later updates from the same CLI.

Terminal

Editable

hulla ui add --framework astro button

Source entering your repository

Generated output

src/components/button/button.astro
src/components/button/button-group.astro

Install preview for button and dialog using default project paths. Registry support files are additional. No CLI command is run or files written.

Edit the install command and see the source files in its install plan. The preview supports Astro, React, and Solid button and dialog components.

Useful for: Installing @hulla/ui and repeating component workflows across projects.

@hulla/args

Reject --port nope before starting your preview server.

Declare flags, options, positionals, and nested commands. Parse their values with Zod validation while keeping raw input and detection metadata available for your own error messages.

preview

Ready to start storefront

Parsed arguments

Generated output

{
  "project": "storefront",
  "port": 8080,
  "open": true
}

The supplied port is a number. Original input: --port 8080.

Runs @hulla/args + Zod. Space-separated tokens; no shell quoting or server startup.

Type a bad port, omit it, or add a flag. Real parsing distinguishes invalid input from absence before your handler runs.

Useful for: Developer tools that need validated input and control over their output.