Skip to content

Upgrade to Lunaria v0.3

This guide will help you upgrade your project from Lunaria v0.2 to v0.3. To update the @lunariajs/core package, see Upgrade Lunaria.

Lunaria v0.3 includes breaking changes to pattern matching. See the Lunaria changelog for full release notes.

If you use the Lunaria GitHub Action, update it to v0.4.

.github/workflows/lunaria.yml
- name: Generate Lunaria Overview
uses: lunariajs/action@v0.3
uses: lunariajs/action@v0.4

In Lunaria v0.2, patterns ignored the casing of paths. For example, with an es locale, src/content/docs/@lang/@path matched src/content/docs/ES/intro.md as a Spanish file.

In Lunaria v0.3, every part of a pattern, including the lang of your locales, must match the casing of the path exactly.

If your directory or file names use a different casing than the lang of your locales, rename one of them to match the other.

If you can’t change either, set a custom parameter to each locale with the casing used in your paths, and use it in your pattern instead of @lang:

lunaria.config.mjs
import { defineConfig } from '@lunariajs/core/config';
export default defineConfig({
sourceLocale: {
label: 'English',
lang: 'en',
parameters: {
dir: 'en',
},
},
locales: [
{
label: 'Português do Brasil',
lang: 'pt-br',
parameters: {
dir: 'pt-BR',
},
},
],
files: [
{
include: ['src/content/docs/en/**/*.md'],
pattern: 'src/content/docs/@lang/@path',
pattern: 'src/content/docs/@dir/@path',
type: 'universal',
},
],
});

Changed: patterns match file paths instead of URLs

Section titled “Changed: patterns match file paths instead of URLs”

Lunaria v0.2 matched patterns as if paths were URLs. Parameters stopped at a # or ?, as if they started a URL hash or query, and a trailing /, #, or ? at the end of a path was ignored.

In Lunaria v0.3, # and ? in paths are matched like any other character, so parameters like :name match file names such as c#.md. A pattern also has to match the entire path, including any trailing characters.

No changes are needed in most projects. If your file names contain # or ?, check that your dashboard still tracks them as expected.

In Lunaria v0.2, some invalid patterns were silently accepted, leaving the affected files unmatched or building wrong paths for them.

In Lunaria v0.3, these patterns make Lunaria stop with an error explaining the problem, pointing to its position in the pattern when possible.

Run lunaria build and update any patterns it reports. The following were accepted in v0.2, but are errors in v0.3:

Problem Example Fix
A group without a parameter doc{s}?/@lang/@path Use a parameter instead, e.g. :dir(docs?)/@lang/@path
A named capturing group inside of a regular expression docs/@lang/:version((?<v>v1|v2))/@path Use a non-capturing group, e.g. :version((?:v1|v2))
A lookbehind inside of a regular expression docs/@lang/:name((?<=a)b)/@path Rewrite the regular expression without the lookbehind
A trailing \ docs/@lang/@path\\ Remove the \, or add the character it should escape
source and locales patterns with different parameters { source: 'docs/:version/@path', locales: 'docs/@lang/@path' } Use the same parameters in both, e.g. locales: 'docs/:version/@lang/@path'
A pattern without a placeholder, using a parameter that only starts like one src/i18n/:pathname Add a placeholder, e.g. src/i18n/@lang/:pathname

@lang and custom parameters can still be used in only one of the source and locales patterns, since they take the values of each locale.

See the pattern syntax reference for everything a pattern accepts.

In Lunaria v0.2, the names of custom parameters could contain any character, even though names with characters like - couldn’t be used in patterns.

In Lunaria v0.3, custom parameter names can only contain letters, numbers, and underscores.

Rename any custom parameters with other characters in every locale, and update the patterns using them:

lunaria.config.mjs
import { defineConfig } from '@lunariajs/core/config';
export default defineConfig({
sourceLocale: {
label: 'English',
lang: 'en',
parameters: { 'file-tag': 'en' },
parameters: { fileTag: 'en' },
},
locales: [
{
label: 'Português do Brasil',
lang: 'pt-br',
parameters: { 'file-tag': 'pt-BR' },
parameters: { fileTag: 'pt-BR' },
},
],
files: [
{
include: ['src/i18n/en.yml'],
pattern: 'src/i18n/@file-tag.yml',
pattern: 'src/i18n/@fileTag.yml',
type: 'dictionary',
},
],
});

Lunaria v0.3 also fixes several cases where a pattern matched the wrong files or built the wrong paths. For example, with both pt and pt-BR locales, the pattern docs/@lang-@path now matches docs/pt-BR-intro.md as a pt-BR file, instead of a pt file named BR-intro.md.

No changes are needed, but the status of some files may change after upgrading. See the Lunaria changelog for the full list of fixes.