Administration user interface

LightNet stores site content in JSON files. That works well for developers, but it can be less convenient for non-technical editors. To make editing easier, LightNet includes an Administration User Interface (Administration UI). The Administration UI provides a graphical editor for creating, updating, and deleting media items and media collections. Under the hood, it 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 still experimental. It is safe to use in real projects, but it still lacks some quality-of-life improvements, such as more comprehensive 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, example-template ships with it preinstalled. You can still follow this guide from the beginning if you want to verify the setup.

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

   npm install @lightnet/sveltia-admin

   Then add the integration to astro.config.mjs.

2. Add the minimum configuration: Update astro.config.mjs to include both the LightNet integration and the Administration UI integration. Here 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({
           //...
       }),
       lightnetSveltiaAdmin({})
     ]
   });

Edit languages through languages.json

The Administration UI can also edit LightNet languages through a languages.json file at the root of your site. 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 finalized.

Extract languages.json

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

Before:

astro.config.mjs

import { defineConfig } from "astro/config"
import lightnet from "lightnet"

export default defineConfig({
  integrations: [
    lightnet({
      languages: [
        {
          code: "en",
          label: {
            en: "English",
            de: "Englisch"
          },
          isDefaultSiteLanguage: true,
        },
        {
          code: "de",
          label: {
            en: "German",
            de: "Deutsch",
          },
          isSiteLanguage: true,
        },
      ],
    }),
  ],
})

After:

astro.config.mjs

import languages from "./languages.json"
import { defineConfig } from "astro/config"
import lightnet from "lightnet"

export default defineConfig({
  integrations: [
    lightnet({
      languages
    }),
  ],
})

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

/languages.json

[
  {
    "code": "en",
    "label": {
      "en": "English",
      "de": "Englisch"
    },
    "isDefaultSiteLanguage": true
  },
  {
    "code": "de",
    "label": {
      "en": "German",
      "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 GitHub.

Accessing your local file system

Use this workflow when 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: In Chrome or another Chromium-based browser, 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 other 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 editing content online. It does this by connecting to a Git host such as GitHub. When used this way, content changes are written as Git commits through the Git host’s web API. Authentication is handled by the Git host as well, so you can manage editor access through 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 works with either GitHub and GitLab as Git hosts. We recommend GitHub for new LightNet projects.

Note

GitHub does not yet support client-only PKCE authentication for this workflow. For now, use an auth proxy such as sveltia/sveltia-cms-auth. GitHub is planning native support for this flow in the future. Track progress in GitHub roadmap issue #1153.

Connect to GitHub

Follow these steps to connect the Administration UI to a GitHub repository.

1. Host your repository on GitHub: Make sure your LightNet project is hosted on GitHub. If you still need to create or move the repository, follow the hosting guide.
2. Deploy an auth proxy: Set up sveltia/sveltia-cms-auth on Cloudflare Workers. Follow the instructions for setting up GitHub authentication in the sveltia-cms-auth README. Copy the public base URL of the deployed proxy.
3. Open your project configuration: Return to your project and open astro.config.mjs.
4. Configure the backend: Add the backend configuration for your GitHub repository:

   astro.config.mjs

   // ...
   export default defineConfig({
     integrations: [
       // ...
       lightnetSveltiaAdmin({
           backend: {
               name: "github",
               repo: "<Owner>/<Repository Name>",
               baseUrl: "https://your-auth-proxy.workers.dev",
           },
       })
     ]
   });

   Set repo to the GitHub repository path and baseUrl to the public URL of your auth proxy service.
5. Use the Administration UI: After your site is deployed, open /admin on your website, click the login button, and authorize access with GitHub. You can now edit media items online. If other people also need access, add them as collaborators or grant access through your GitHub organization.

Note

Even if you configure a GitHub backend, you can still use a local 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.

Caution

If your site has stricter security requirements, consider changing the default admin path to something 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: "github", repo: "your-org/your-site", baseUrl: "https://your-auth-proxy.workers.dev" }
required: false

This option configures the Git host the Administration UI connects to. LightNet currently supports GitLab and GitHub backends. Its fields map directly to the Sveltia CMS settings for GitHub or GitLab backends.

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 the service that handles the authentication request.

See the Sveltia CMS documentation for more details.

Note

GitHub does not yet support client-only PKCE for this flow. For now, use an auth proxy such as sveltia/sveltia-cms-auth and point baseUrl to that service.

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 the 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. This is the default and currently the only supported option.

See the Sveltia CMS documentation for more details.

experimental

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

Optional experimental features for the Administration UI. If omitted, all experimental features remain 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 }) configuration and import the array from ./languages.json in astro.config.mjs. The languages.json file must live at the root of the site repository.

experimental.fileStorage

type: object
example: { name: "cloudflare-r2", accessKeyId: "your-access-key-id", ... }
required: false

External file storage configuration for Administration UI uploads.

Use this when your Git repository should not be used for file storage, or when your hosting setup needs larger uploads. For example, Cloudflare Workers only allows files up to 25 MB.

LightNet currently supports Cloudflare R2 for this option. Because this feature is experimental, the configuration may change in future releases. See Setup large file storage for a full walkthrough.

experimental.fileStorage.name

type: "cloudflare-r2"
required: true

Selects Cloudflare R2 as the upload storage backend.

experimental.fileStorage.accessKeyId

type: string
required: true

The R2 Access Key ID used for uploads.

experimental.fileStorage.bucket

type: string
required: true

The R2 bucket name used to store uploaded files.

experimental.fileStorage.accountId

type: string
required: true

Your Cloudflare account ID. LightNet uses it to construct the R2 API endpoint.

experimental.fileStorage.publicUrl

type: string
required: true

Public base URL used for previews and downloads of uploaded files. This is required because the R2 S3 API itself always requires authentication.

experimental.fileStorage.prefix

type: string
example: "uploads/"
required: false

Optional path prefix inside the bucket where uploaded files should be stored.