Authlance Layout, Branding & Operations

Part of the Authlance Extension Guide.

This chapter focuses on the presentation layer plus the operational bits that keep the Taco Fish Stand dashboard shippable: layout hooks, theming, package distribution, and the local dev stack.

Layout Overview

The @authlance/sidebar package wraps the entire dashboard with SidebarProvider, AppSidebar, and the header stack defined in HomeComponent. Key behaviors to keep in mind:

  • Primary sidebar (AppSidebar) — shows / routes where navBar is true. It automatically groups entries by RouteCategory and hides anything gated behind roles the current user lacks; if a route is navBar: true and does not have a group, an icon is required.
  • Plain layout (PlainLayout) — a minimal layout without sidebar or header, useful for public pages or embedded experiences.

Because layout components simply read contributions, most customizations boil down to supplying the right data (routes, actions, branding) rather than editing the layout code directly. You can always extend or override the layout components if you need more control.

Branding & Theme

Authlance surfaces brand assets through useBrandLogo / useBrandIcon, both of which read from the example assets that ship with the workspace. Swap these SVGs (or drop in PNGs) under examples/browser/src/assets/brandlogo.svg and examples/browser/src/assets/brandicon.svg to update the logotype that appears in the header, sidebar, and docs shell. The Taco Fish Stand replaces those files with its own taco mascot without touching any React code.

For colors and typography, edit examples/browser/src/styles/index.css. The file follows the shadcn/ui Tailwind v3 token approach so you can redefine CSS variables (e.g., --background, --primary, --sidebar-background) and utility classes in one place. Because the same stylesheet is bundled by the Webpack dev server and SSR pipeline, changes propagate to both the public landing pages and the authenticated dashboard instantly.

Package Distribution & Build Registration

GitHub Packages

All scoped packages @authlance are published to GitHub Packages. Configure your .npmrc so the workspace installer can pull them:

@authlance:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN_WITH_READ_PACKAGES}
always-auth=true

Use a GitHub personal access token with the read:packages scope.

loopExtensions in package.json

Authlance’s backend and webpack generators rely on the loopExtensions field to find your compiled container modules. The Taco Fish package declares both entry points:

{
  "name": "@eltacofish/dashboard",
  "loopExtensions": [
    {
      "frontend": "lib/browser/tacofish-frontend-module",
      "backend": "lib/node/tacofish-backend-module"
    }
  ]
}

During backend-generator and webpack-generator runs (see @authlance/application-manager), the toolchain resolves these paths to wire up containers, CLI commands, and webpack entry points. Always point to compiled JavaScript (lib/**), not the TypeScript sources.

Development Environment (Node 20 + Docker Compose)

  1. Node.js 20 — Install the LTS toolchain (nvm install 20, nvm use 20) before running any workspace scripts. The repo’s TypeScript config already targets Node 20 libraries, so older runtimes will fail on optional chaining and newer DOM types.
  2. Python 3.9+ — Make sure you have Python 3.9 or later installed. You can use pyenv to manage your Python versions (build requirement).
  3. Install dependencies — From the repo root, run yarn install. This pulls the private @authlance/* packages (make sure .npmrc is configured as shown above).
  4. Bootstrap the backend stack:
    • cd deployment/docker-compose.
    • Copy ./.env.template to .env and adjust DSNs, secrets, Stripe keys, and license references.
    • Get your trial license with your Authlance account.
    • Start everything: ./start.sh. The script brings up MySQL → ORY (Kratos/Hydra) → auth → license operator → nginx with health checks.
  5. Run the dashboard against the stack:
    • Open VS Code (launch configs are preconfigured).
    • Open a new terminal, stay on Node 20, and run yarn run watch (or yarn run start:webpackdev at the repo root). The project also ships with a launch.json that configures a dev server which sets DEV_PROXY_WEBPACK=true; this enables proxying of webpack dev server requests.
    • Modify the app-config.json file.
    • The workspace contains only one launch configuration—use it to launch the dashboard.

This setup mirrors production closely: Docker hosts the stateful services, while the Node 20 dev server runs on the host for fast reloads.