Migrate to Lume 4

Guide to migrate your project from Lume 3 to Lume 4

Lume 4 runs on Node, so make sure you have installed the version 24 LTS or newer in your computer. See Node documentation for more info.

The code is published on NPM under the @lumeland organization:

For example, the typical _config.ts file in Lume 3:

// Lume 3 (Deno)
import lume from "lume/mod.ts";
import basePath from "lume/plugins/base_path.ts";

const site = lume();

site.use(basePath());

export default site;

Will become as follows in Lume 4:

// Lume 4 (Node)
import lume from "@lumeland/lume";
import basePath from "@lumeland/plugin-base-path";

const site = lume();

site.use(basePath());

export default site;

Command line interface

Lume 4 registers the lume binary command in NPM. The build and serve tasks in Deno are now NPM scripts. Make sure you have this in your package.json:

{
    "scripts": {
        "serve": "lume build -s",
        "build": "lume build"
    }
}

Now you can run npm run serve and npm run build to server and build the site. With other package managers like pnpm or yarn is even shorter: pnpm serve and pnpm build.

Automatic migration

The way to setup Lume 3 for new projects is using the init script deno run -A https://lume.land/init.ts. The equivalent script in Lume 4 is npm create lume. You can specify the project folder in the first argument. For example npm create lume . will create a new project in the current folder.

The script detects if the folder already contains a Lume project and will ask you to migrate it to Node. If you confirm this action, it will create the files package.json and tsconfig.json and will install all dependencies detected in the deno.json and _config.ts files.

Note that this migration may not be complete. Depending on your site and configuration, maybe you need additional changes in your code. The script doesn't remove the Deno files (deno.json and company), just create the new files so once your site is completely migrated, you will need to remove these files by yourself.

LumeCMS

To setup LumeCMS, you need to install two packages: the standalone CMS is @lumeland/cms, and to use it with Lume you need the plugin @lumeland/plugin-cms.

LumeCMS is no longer detected automatically. You must include the plugin in your _config.ts file:

// _config.ts
import lumeCms from "@lumeland/plugin-cms";
import cms from "./_cms.ts";

site.use(lumeCms({ cms }));

The GitHub storage was removed from the CMS core and moved to a different package:

// _cms.ts
import createCms from "@lumeland/cms";
import GitHub from "@lumeland/cms-github";

const cms = createCms();

cms.storage("src", GitHub.create("org/repo", "token"));

Plugin changes

  • The plugins brotli, gzip and the middleware precompress were merged in the compress plugin.
  • The redirects plugin includes also the redirects middleware, and the option strict was removed.
  • The remark plugin no longer overrides the md filter but registers mdRemark.
  • The plugin pagefind replaces the old UI with the new one based on web components.
  • The option includes has been removed in all plugins supporting it.
    • In the postcss and lightningcss plugins this option enabled or disabled the bundle. It was replaced by the new boolean option bundle.
  • The middlewares reload and no-cache were merged into dev, a new plugin containing everything needed for development (watch or serve mode). This plugin is used internally by Lume you don't need to import it.
  • Added the new plugin markdown-footnotes to support footnotes (only in markdown files rendered with markdown-it).
  • The following plugins were not ported to Node (for now). If you really need them, please open an issue explaining your use case.
    • attributes
    • fff
    • relations
    • decap-cms
    • middleware redirect as2
    • middleware logger
    • cache busting
    • shutdown
    • www

Themes

For now, only the following themes were migrated:

More themes will be included in the future.

Edit this page