App configuration: app.iwc and package.iwc

app.iwc

Purpose: the application itself: its name, look (theme), global stylesheets, <head> defaults, authentication, database, uploads, multi-tenancy and the 404 screen. When: exactly one per project, at the root. iwc create writes it. A project without it does not compile.

Complete example

{
  "name": "Lumen & Oak",
  "iwc": 1,
  "description": "Handmade lighting and furniture.",
  "theme": {
    "tokens": {
      "color-primary": "#1f3a2e",
      "color-on-primary": "#fdfbf7",
      "color-text": "#1b1b18",
      "color-background": "#fdfbf7",
      "color-surface": "#f3efe6",
      "color-border": "#e4ddcf",
      "color-link": "#1f3a2e",
      "radius": "14px",
      "font-body": "'DM Sans', system-ui, sans-serif",
      "font-heading": "'Fraunces', Georgia, serif",
      "section-pad": "96px"
    },
    "dark": {
      "color-text": "#f3efe6",
      "color-background": "#141412",
      "color-link": "#9fd3b4"
    },
    "fonts": [
      { "family": "DM Sans", "google": true, "weights": [400, 500, 700] },
      { "family": "Brand Serif", "source": "/assets/fonts/brand.woff2", "weight": "700" }
    ]
  },
  "breakpoints": { "mobile": 640, "tablet": 1024 },
  "styles": ["styles/theme.css", "styles/main.css"],
  "head": { "title": "%s · Lumen & Oak", "description": "Made by hand.", "favicon": "/assets/favicon.svg", "lang": "en" },
  "auth": {
    "user": "user.schema.iwc",
    "identity": "email",
    "password": "password",
    "role": "role",
    "defaultRole": "customer",
    "loginPage": "/login",
    "register": true,
    "session": { "ttl": "7d" }
  },
  "database": { "url": { "env": "STORE_DATABASE_URL" } },
  "storage": { "maxUploadSize": "2MB", "allow": ["image/png", "image/jpeg", "image/webp"] },
  "notFound": "not-found.ui.iwc"
}

Properties

theme

• tokens: any names you like, emitted as CSS custom properties on :root. "color-primary": "#1f3a2e" becomes var(--color-primary), usable in every stylesheet and every style. The built-in elements read these tokens:

  Token	Used for
  color-primary, color-on-primary	primary buttons, active tabs, charts
  color-text, color-background	the page
  color-surface, color-border	cards, inputs, tables, dropdowns
  color-link	links (default: the text colour)
  color-danger	field errors
  color-rating	review stars
  radius	buttons, cards, inputs
  font-body, font-heading	body text and h1–h6
  carousel-gap	space between carousel slides

• dark: token overrides applied when the visitor's system is in dark mode (prefers-color-scheme: dark). Override at least the background and text, and any brand colour used as text on the background (a dark green link is unreadable on a near-black page).

• fonts: each is {family, google, weights} (loaded from Google Fonts) or {family, source, weight, style} (a file under assets/, emitted as @font-face). Refer to the family in a token, e.g. "font-body": "'DM Sans', sans-serif".

Common mistakes

package.iwc

Purpose: packaging metadata and deploy targets.

{
  "name": "lumen-oak",
  "version": "1.2.0",
  "iwc": 1,
  "deploy": {
    "prod": { "domain": "lumen-oak.com", "aliases": ["www.lumen-oak.com"], "email": "ops@lumen-oak.com" },
    "staging": { "domain": "staging.lumen-oak.com", "port": 8081 },
    "legacy": { "url": "https://deploy.example.com", "tokenEnv": "IWC_DEPLOY_TOKEN" }
  }
}

You rarely write targets by hand: iwc deploy <name> asks and writes them. "type": "cpanel" is shared hosting reached through cPanel's API (cPanel); a target with a url is an iwc host you run yourself, reached over HTTPS with a token; any other target is a server reached over SSH and set up by iwc deploy (your own server). The connection itself — address, user, port, key — is kept per developer in ~/.iwc/deploy/, never in the project; write "ssh": "deploy@203.0.113.10" only to share one address with the whole team.

If package.iwc is missing, the project still runs, as app 0.0.0.