nuxt-light

This is a Hostlink nuxt-light framework for Nuxt.

• ✨  Release Notes
• 📖  Documentation

Features

• HostLink nuxt-light framework

Quick Setup

1. Add nuxt-light dependency to your project

# Using npm
npm install --save-dev @hostlink/nuxt-light

2. Add @hostlink/nuxt-light to the modules section of nuxt.config.ts

import pkg from './package.json'
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      //apiBase: 'your-api-base-url'
      appVersion: pkg.version
    }
  },
  ssr:false,
  modules: [
    '@hostlink/nuxt-light'
  ]
})

That's it! You can now use nuxt-light in your Nuxt app ✨

API clients

nuxt-light supports multiple Light API endpoints. The client named auth is always the default: when a component or composable does not specify a client, the request is sent to auth.

Configure named clients in nuxt.config.ts:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      light: {
        clients: {
          auth: {
            baseURL: 'https://auth.example.com/graphql',
          },
          business: {
            baseURL: 'https://business.example.com/graphql',
            audience: 'business-api',
          },
          infra: {
            baseURL: 'https://infra.example.com/graphql',
            audience: 'infra-api',
            healthURL: 'https://infra.example.com/health',
            healthTimeout: 3000,
            unavailableMessage: 'Connect to the company network or VPN.',
          },
        },
      },
    },
  },
  modules: [
    '@hostlink/nuxt-light',
  ],
})

A client can also be configured with a URL string:

clients: {
  auth: '/auth-api/',
  business: '/business-api/',
}

Clients with an audience obtain a short-lived audience token lazily from the default auth client. The token is cached by that client, refreshed shortly before expiry, and sent as a Bearer token automatically:

Authorization: Bearer <audience-access-token>

Components and composables do not need to fetch or attach tokens themselves. For example, the first request made by this table automatically requests a business-api token from Auth:

<L-Table client="business" model-name="Order" />


### Client availability and menus

When a client has a `healthURL`, nuxt-light checks it on startup, when the
browser comes back online, and when the tab becomes visible. Menu items can
declare that they require that client:


```yaml
- label: Servers
  icon: sym_o_dns
  to: /Server
  permission: server.list
  requiresClient: infra

L-Menu keeps the authorized item visible, but disables it and shows the configured message while the client is checking or unavailable. Applications can use the same state for route guards or page notices:

const availability = useLightClientAvailability()

if (!availability.isAvailable('infra')) {
  // Show a company-network/VPN notice.
}

Clients without a healthURL remain available and keep the previous behavior.

### Backwards-compatible single endpoint

The existing `public.apiBase` setting is still supported. When no named
`auth` client is configured, `apiBase` is registered as the `auth` client:

```ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: '/api/',
    },
  },
})

If neither setting is provided, the default Auth API URL is /api/.

Selecting a client

Use useLightClient() without an argument to get the Auth API client:

const auth = useLightClient()
const business = useLightClient('business')

await auth.auth.login(username, password)
await business.query({
  app: {
    orders: {
      order_id: true,
    },
  },
})

The standard composables also default to auth:

await q(query)                         // auth
await q(query, 'business')             // business

model('User')                          // auth
model('Order', 'business')             // business

collect('User', fields)                // auth
collect('Order', fields, 'business')   // business

await m('updateUser', args, fields)                    // auth
await m('updateOrder', args, fields, 'business')       // business

<L-Table> uses auth unless its client prop is provided:

<template>
  <!-- Uses the default auth client -->
  <L-Table model-name="User" />

  <!-- Uses the business client -->
  <L-Table
    client="business"
    model-name="Order"
  />
</template>

An unknown client name throws an explicit configuration error instead of silently sending the request to another endpoint.

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release

app.vue

<template>
  <l-app/>
</template>

Google Sigin

nuxt.config.ts

 app: {
    head: {
      script: [
        {
          src: 'https://accounts.google.com/gsi/client',
          async: true,
          defer: true,
        }
      ]
    }
  }

OAuth resource and client management

/OAuthResource manages service URLs, display names, allowed scopes and enabled state. It supports create, update and delete using light-oauth2 resource-management GraphQL. The searchable scope selector uses Light’s registered concrete permissions, optionally restricted by OAUTH_SCOPES. A resource URL is immutable after creation. Disabling a resource blocks existing tokens as well as new authorizations; removing a scope narrows existing access.

The backend must apply 002_oauth_resources.sql, register trusted resources. Its resource menu is available whenever OAuth is enabled. Assign oauth_resource.list, oauth_resource.add, oauth_resource.update and oauth_resource.delete as appropriate; the UI hides actions the user cannot perform and the backend enforces the same rights.

/OAuthClient lets administrators assign enabled resources to clients. Scope choices are limited to the selected resources and the provider's exposed scopes. The Test authorization dialog selects one enabled resource assigned to the client and offers only matching client scopes. A legacy client without explicit assignments uses the backend's default resource.

The backend query oauthClientResourcePolicy (protected by oauth_client.list) supplies registry mode, default resource and the resource catalog. Resource CRUD still requires the separate oauth_resource.* permissions. Both the updated backend and this module are required for DB resource selection. With registry mode disabled, client management retains its compatibility behavior. Older backends without the policy query retain manual Resource URL entry in the test dialog.

OAuth login and consent UI

The module provides a public /oauth/authorize page with login, a two-factor code field, individual scope checkboxes, and Allow/Deny. It works with the optional frontend flow in light-oauth2; the API keeps the OAuth entry endpoint, verifies all permissions and consent submissions, and issues authorization codes. The page does not store OAuth access tokens.

export default defineNuxtConfig({
  modules: ['@hostlink/nuxt-light'],
  light: {
    oauth: { apiBase: 'https://api.example.com/' },
  },
})

On the API, set OAUTH_AUTHORIZATION_UI_URL=https://app.example.com/oauth/authorize. To offer the current client/user/provider permission intersection when the client omits scope, also set OAUTH_AUTO_SELECT_SCOPES=true.

Clients continue to open the API's /oauth/authorize. It validates the request and redirects to the frontend with a short-lived request ID. The page exchanges view data and CSRF-protected submissions with /oauth/interaction using API browser cookies; it only displays scopes offered by the server. API and frontend must be same-site (for example two HTTPS subdomains), or use the same loopback hostname for local development. Do not mix localhost and 127.0.0.1. Configure the public API URL directly rather than a development proxy that changes cookie paths. Native Light cookie settings and the API's PHP session storage must support this setup.

light.oauth.apiBase also supports runtimeConfig.public.light.oauth.apiBase and NUXT_PUBLIC_LIGHT_OAUTH_API_BASE; when empty it falls back to runtimeConfig.public.apiBase. The route is marked lightOAuth so module permission middleware and <l-app> do not replace it with the regular application login. An application with its own auth wrapper or global middleware must likewise let this public OAuth route render. Route query parameters cannot supply an API URL, client identity, or extra scopes. Custom OAuth route prefixes require a corresponding interaction endpoint integration rather than the default page's /oauth/interaction path.