Administration user interface

LightNet stores site content in JSON files. This works well for developers, but it can be harder for non-technical editors. To make content editing easier, LightNet provides an Administration User Interface (Administration UI). The Administration UI lets you create, update, and delete media items and media collections through a graphical editor. To implement the interface, LightNet uses Sveltia CMS.

Changes made in the Administration UI are written either to your local file system or to a Git host.

Experimental

The Administration UI is an experimental feature. It is safe to try in real projects, but it still lacks some quality-of-life features, such as more extensive validation for invalid content changes.

Add the Administration UI to your project

Follow these steps to add the Administration UI to your LightNet project:

Note

Your template may already include the Administration UI. For example, the example-template ships with it preinstalled. You can still follow this guide from the beginning if you want to verify the setup.

1. Add the integration: Install the LightNet Administration UI integration (@lightnet/sveltia-admin) from your project folder:

   npm install @lightnet/sveltia-admin

   Then add the integration to your astro.config.mjs file.

2. Add minimal configuration: Update astro.config.mjs with both the LightNet integration and the Administration UI integration. This is a minimal example:

   astro.config.mjs

   import lightnetSveltiaAdmin from "@lightnet/sveltia-admin"
   import { defineConfig } from "astro/config"
   import lightnet from "lightnet"
   
   export default defineConfig({
     integrations: [
       lightnet({
           title: {
             en: "My Library",
           },
           languages: [
             {
               code: "en",
               label: {
                 en: "English",
               },
               isDefaultSiteLanguage: true,
             },
           ],
           //...
       }),
       lightnetSveltiaAdmin({})
     ]
   });

Caution

For sites with higher security requirements, we recommend changing the default admin path to something less guessable. You can do this with the path option.

Edit languages through languages.json

The Administration UI can also edit LightNet languages through a root-level languages.json file. This is controlled by the experimental useLanguagesCollection option in lightnetSveltiaAdmin(...).

Enable the experimental option in astro.config.mjs:

astro.config.mjs

lightnetSveltiaAdmin({
  experimental: {
    useLanguagesCollection: true,
  },
})

When enabled, the Administration UI expects a languages.json file at the root of your LightNet site.

Experimental option

This workflow is optional and experimental. The option name and behavior may still change before the feature is stabilized.

Extract languages.json

If your site currently defines languages inline inside lightnet(...), move that array into a dedicated languages.json file and import it back into astro.config.mjs.

Before:

astro.config.mjs

lightnet({
  languages: [
    {
      code: "en",
      label: {
        en: "English",
      },
      isDefaultSiteLanguage: true,
    },
    {
      code: "de",
      label: {
        en: "Deutsch",
        de: "Deutsch",
      },
      isSiteLanguage: true,
    },
  ],
})

After:

astro.config.mjs

import languages from "./languages.json"

lightnet({
  languages,
})

lightnetSveltiaAdmin({
  experimental: {
    useLanguagesCollection: true,
  },
})

Create languages.json at the site root with the same array:

languages.json

[
  {
    "code": "en",
    "label": {
      "en": "English"
    },
    "isDefaultSiteLanguage": true
  },
  {
    "code": "de",
    "label": {
      "en": "Deutsch",
      "de": "Deutsch"
    },
    "isSiteLanguage": true
  }
]

Run the Administration UI

The Administration UI can save changes either to your local file system or to a Git host such as GitLab or GitHub.

Accessing your local file system

Use this workflow while developing locally on your own computer.

1. Start the development server: Run this command from your project folder:

   npm run dev

   This starts the LightNet development server.
2. Open the Administration UI: Open Chrome or another Chromium-based browser and go to localhost:4321/admin.
3. Choose the local workflow: Click the “Work with Local Repository” button.
4. Grant folder access: When your browser prompts you, select your project folder and allow access.

Note

The local admin workflow requires the File System Access API, which is currently available only in Chrome and Chromium-based browsers. Brave disables this API by default; you can enable it at brave://flags/#file-system-access-api.

The online admin workflow works in all major browsers.

Accessing a Git host

The Administration UI also supports online editing of a site’s content. This works by connecting the Administration UI to a Git host such as GitLab or GitHub. When used online, content changes are written as Git commits through the Git host’s web API. Authentication is also handled by the Git host, so you can manage editor access through your repository permissions.

This architecture has several advantages:

• No need to deploy and maintain a custom backend API.
• Security is handled by the Git host, including support for two-factor authentication.
• Git history makes it easy to review changes and roll back when needed.
• Git repositories can often be hosted at low or no cost.

LightNet supports both GitHub and GitLab as Git hosts. We strongly recommend GitLab because it supports browser-based authentication for this workflow.

Note

If you need to use GitHub as your Git host, note that GitHub only supports server-side authentication for this flow. That means you need an additional backend service to forward the authentication request.

Connect to GitLab

To connect your Administration UI to a GitLab repository, follow these steps.

1. Host your repository on GitLab: Make sure your LightNet project is hosted on GitLab. If you still need to move or create the repository there, follow the hosting guide.
2. Open the GitLab group settings: On GitLab.com, open the group that owns the repository and go to its Settings.
3. Create an application: Open the Applications settings and choose Add new application.
4. Configure the application: In the form, use these settings:
   • Name: Choose a descriptive name, for example your site name.
   • Redirect URI: Enter the final URL of your LightNet site followed by the admin path, for example https://your-library.com/admin/. Do not forget the trailing slash.
   • Confidential: Disable this option.
   • Scopes: Select the api scope.
5. Copy the Application ID: After saving, GitLab shows the new Application ID. Copy it for the next step.
6. Open your project configuration: Return to your project and open astro.config.mjs.
7. Configure the backend: Add the backend configuration for your GitLab repository:

   astro.config.mjs

   // ...
   export default defineConfig({
     integrations: [
       // ...
       lightnetSveltiaAdmin({
           backend: {
               name: "gitlab",
               repo: "<Group>/<Repository Name>",
               appId: "<Application ID>",
           },
       })
     ]
   });

   Set repo to the GitLab repository path, and set appId to the Application ID you copied in step 5.
8. Use the Administration UI: After your site is deployed, open /admin on your website, click the login button, and authorize access with GitLab. You can now edit media items online. If someone else also needs access, add their account to the GitLab group.

Note

Even when you have configured a GitLab backend, you can still use a locally configured Administration UI workflow during development.

Reference

You can pass the following options to the lightnetSveltiaAdmin integration inside astro.config.mjs:

astro.config.mjs

import lightnet from "lightnet";
import lightnetSveltiaAdmin from "@lightnet/sveltia-admin";
import { defineConfig } from "astro/config";

export default defineConfig({
  integrations: [
    lightnet({...}),
    lightnetSveltiaAdmin({
      /* add config here */
    }),
  ],
});

path

type: string
example: "admin"
required: false
default: "admin"

The path where the Administration UI is available on your site. Change this path to make your Git host connection less guessable.

maxFileSize

type: number
example: 15
required: false
default: 25

The maximum file size, in megabytes, that can be uploaded. The default is 25 MB, which aligns with Cloudflare’s maximum file size.

backend

type: object
example: { name: "gitlab", repo: "your-org/your-site", appId: "12345abcd" }
required: false

This configures the Git host your Administration UI connects to. LightNet currently supports GitLab and GitHub backends. The configuration maps to the Administration UI backend settings for GitHub or GitLab.

backend: "gitlab"

GitLab backend configuration has these options:

• name: "gitlab" (required) selects GitLab as the backend.
• repo: string (required) the GitLab repository path of your site.
• appId: string Application ID from the site’s GitLab settings.
• branch: string the branch used by the Administration UI. The default is "main".
• authType: "pkce" the authentication type to use. The default, and currently the only supported option, is "pkce".

backend: "github"

GitHub backend configuration has these options:

• name: "github" (required) selects GitHub as the backend.
• repo: string (required) the GitHub repository path of your site.
• branch: string the branch used by the Administration UI. The default is "main".
• baseUrl: string the URL of your service doing the authentication request.

Note

GitHub does not support the PKCE authentication type. This means you need an authentication server to handle the authentication request. This is why we recommend using the GitLab backend for LightNet sites.

experimental

type: object
example: { useLanguagesCollection: true }
required: false

Optional experimental features for the Administration UI. If omitted, experimental features stay disabled.

experimental.useLanguagesCollection

type: boolean
example: true
required: false
default: false

Enables Administration UI editing for LightNet languages through a root-level languages.json file. When this option is enabled, keep your lightnet({ languages }) config and import the array from ./languages.json in astro.config.mjs. The languages.json file must live at the root of the site repository.