Remote files

Load remote files as a fallback of missing local files

In Lume, it's possible to use remote files as if they were local files. To configure a remote file, you must set a local name and a remote URL in your _config.ts file using the remote() function. For example:

import lume from "lume/mod.ts";

const site = lume();

site.remote("styles.css", "https://example.com/theme/styles.css");

export default site;

This configure Lume to use the content of the remote URL as fallback if the file styles.css doesn't exist locally.

To try this, we need to use the file somewhere (Lume only download it if it's used). If we're using a plugin like postcss or lightningcss, we can import the file in your CSS with:

@import "/styles.css";

Because the file doesn't exist in your local folder, Lume will download the content from the URL.

Add remote files

If you only want to copy the file from an URL, the simplest way is using the site.add function that supports URL.

site.add("https://example.com/theme/styles.css", "styles.css");

Remote layouts

Remote files can be used for layouts. Let's say you have several websites using the same layout. Instead of repeating the same file in every project, you can load it remotely:

site.remote(
  "_includes/layouts/main.vto",
  "https://example.com/theme/layouts/main.vto",
);

Now, you can use this layout in all your files:

---
title: This is a page
layout: layouts/main.vto
---

Page content

Override remote files

If a remote file exists locally, it will be used instead of the remote one. This is useful for creating themes with all templates and assets loaded remotely but allowing overriding some files locally in order to customize the theme. As an example, see the Simple blog theme.

Multiple remote files

For multiple remote files from the same origin, it's possible to use an array of files as the third argument:

const files = [
  "styles.css",
  "components/button.css",
  "components/alert.css",
  "components/icons.css",
];

site.remote("/styles/", "https://example.com/styles/", files);

The four files defined in the files variable will be downloaded from https://example.com/styles/ and assigned to the /styles/ local folder. In other words, it's equivalent to:

site.remote("/styles/styles.css", "https://example.com/styles/styles.css");
site.remote(
  "/styles/components/button.css",
  "https://example.com/styles/components/button.css",
);
site.remote(
  "/styles/components/alert.css",
  "https://example.com/styles/components/alert.css",
);
site.remote(
  "/styles/components/icons.css",
  "https://example.com/styles/components/icons.css",
);

Glob patterns

Some specifiers are compatible with glob patterns:

site.remote("/styles/", "https://cdn.jsdelivr.net/gh/user/repo/styles/", [
  "**/*.css",
]);

In the example above, all .css files found in the folder are automatically asigned to the /styles/ local folder. Note that glob patterns are compatible only for the following specifiers:

  • npm: to use NPM packages (like npm:lucide-static@0.544.0)
  • gh: to use GitHub repositories (like gh:lumeland/theme-simple-wiki)
  • file: to use local files
  • URLs starting with https://cdn.jsdelivr.net/.

Limits of remote files

Remote files work in most cases, because they are integrated natively in Lume's file system. Some template engines like Vento, Nunjucks or Liquid use the Lume's file system to load the templates hence they are compatible with remote files.

Eta and Pug don't allow customizing how they load files, hence they cannot include remote files. If you want to use remote templates, Vento or Nunjucks are good options.

Import modules

JavaScript/TypeScript modules imported as import foo from "./filename.ts" are not managed by Lume's file system, but you can use import maps for a similar behavior.

Cache

Remote files are automatically cached using the Web Cache API, so they are requested only the first time. After that, you don't need network access and can work offline.

If you don't want to cache the remote files, use the LUME_NOCACHE=true environment variable

Note that LUME_NOCACHE also disables the _cache folder used to store the processed images. To disable only the cache for remote files, use a Lume event:

import { clearCache } from "lume/core/utils/read.ts";

site.addEventListener("beforeBuild", clearCache);

For a deeper customization, you can access to the cache storage using the global caches object:

// Remove the cache of a specific URL
const cache = await caches.open("lume_remote_files");
await cache.delete("https://example.com/theme/styles.css");

// Or remove all cached files
await caches.delete("lume_remote_files");
Edit this page