Configuration

JAF configuration lives in config/jaf.config.js. The file is optional - every option has a default, and a scaffolded project runs without touching it.

It is read as plain ESM by both the Vite plugins at build time and the router at runtime.

Shape

// config/jaf.config.js
export default {
  componentsPath: '/pages/components',
  scanPaths: ['pages'],

  router: {
    root: '#app',
    fileRouting: true,
    prefetch: true,
    transitions: 'fade',
  },

  routing: {
    pagesDir: 'pages',
    layoutFile: 'layout.html',
    errorsDir: 'errors',
    ignore: ['components/**', 'partials/**', 'shared/**'],
  },

  guards: {
    redirect: '/login',
  },

  runtimeCompile: false,
  leanRuntime: 'auto',

  query: {
    adapter: 'basic',
  },

  namespaces: {
    libraries: { flowbite: 'lib/flowbite' },
    warnOnConflicts: true,
  },
}

Component Resolution

scanPaths can also be passed inline to the Vite plugin.

The inline value wins; jaf.config.js is only consulted when the plugin was given none.

// vite.config.ts
jafComponentsPlugin({ scanPaths: ['pages', 'lib'] })

Router

router.basePath

Set this when the app is served from a subdirectory rather than the root of a domain - https://example.com/app/ instead of https://example.com/.

router: {
  basePath: '/app',
}

Your route table stays exactly as it is.

The prefix is stripped from every URL arriving from outside - a link href, a navigate() call, the first load, a back or forward - and added back to every URL the router writes.

Everything in between is prefix-free: route.path is '/about', so route names, guards, active links and generatePath() keep working untouched.

The strip is tolerant, so both spellings of a link reach the same route and both end up in the address bar as /app/about.

The prefix has to end on a segment boundary, so /application/about is a different place and 404s as it should.

'/app', 'app', '/app/' and 'app/' are one configuration; '' and '/' both mean "served at the root".

In mode: 'hash' the prefix belongs to the document's own path and never appears after the #, so basePath does nothing there - serve the app from the subdirectory and hash routing works unchanged.

router.transitions

Either a single value applied to every navigation:

router: {
  transitions: 'fade',
}

Or an object with a default and per-route overrides:

router: {
  transitions: {
    default: 'fade',
    routes: {
      '/gallery/*': 'zoom',
      '/docs/**': 'none',
    },
  },
}

Omitting transitions entirely disables them. Supplying routes without a default makes the default 'fade'.

The most specific matching route pattern wins over default, and a per-navigation option beats both. See Route transitions for the full surface.

Routing

These can also live in config/routing.js, which is merged into the same routing namespace.

Use whichever you prefer, not both.

Guards

The allow list itself is a different file - config/guards.config.js. This is the one guard decision the build makes.

Compilation

Query

See Adapters for the behavioural differences.

Namespaces

See Component Namespaces.

Multiple Apps

apps: {
  '/admin': 'admin.html',
  '/': 'index.html',
}

Build Configuration

Chunking and build tuning live in a separate file, config/build.js, because they are consumed by vite.config.ts rather than by JAF itself:

Vite Plugins

JAF is a set of Vite plugins.

Most take no options; the ones that do are configured inline in vite.config.ts, not in jaf.config.js:

See TypeScript for what the codegen plugins emit.