Skip to content

Upgrading from 1.x

This guide walks through moving an existing Alinea 1.7 project to 2.0. Your content files don't need a migration and the query API is unchanged. Most projects only need new runtime versions, one config option and a look at their media URLs. The dashboard was rebuilt, so custom dashboard code needs the most attention.

Checklist

  1. Run Node.js 24 or higher, locally, in CI (scheduled jobs that run the alinea CLI too) and wherever your site runs, and use React 19.

  2. Update the package: npm install alinea@latest (or pnpm add, yarn add, bun add).

  3. Add handlerUrl to your config, it is now required, and set baseUrl.production (or make handlerUrl absolute). Replace dashboardFile with adminPath.

  4. Make sure your Next.js config is wrapped in withAlinea and your scripts run alinea dev -- next dev and alinea build -- next build: media URLs are now served through your site.

  5. Media: replace image.url with image.src and use the URLs Alinea returns instead of building them from location. alinea build warns about media files that store a url as their location, alinea build --fix repairs them.

  6. Move children of Config.media(...) into its children option.

  7. Remove the options of Field.metadata(...) and the step option of Field.time.

  8. Rich text: pass extensions as a function, upgrade custom extensions to Tiptap 3 and render custom attributes as data-* attributes.

  9. Handler: replace remote with backend, and move entry hooks to beforeCommit / afterCommit.

  10. Self-hosted OAuth2: provide validateClaims.

  11. Custom field views and dashboard code: import hooks from alinea/cms and components from alinea/components instead of alinea/dashboard and alinea/ui, replace useEntryEditor with useEntry and rename the theme tokens your CSS reads.

  12. Run alinea build, open the dashboard and save an entry to review the diff.

  13. Upgrading from a 2.0 preview instead? See From a 2.0 preview.

Runtime requirements

Node.js 24 or higher. The CLI exits with "Alinea requires Node version 24 or higher" on older versions. The bundled content database is opened with Node's built-in node:sqlite (or bun:sqlite under Bun), so the runtime that serves your site needs Node 24 too, not only the machine that builds it. The same goes for scheduled CI jobs that run the alinea CLI, such as a nightly alinea build or a script that imports content: update the Node version in those workflows as well.

React 19. react and react-dom 19 are now peer dependencies and the CLI checks for them. In practice that means Next.js 15 or newer. Check third-party React renderers too: libraries built on React 18 internals, such as older versions of react-three-fiber or react-pixi, break under React 19. Upgrade them to a version that supports React 19.

Configuration

handlerUrl is required

Alinea 1.7 assumed /api/cms when handlerUrl was missing. Alinea 2.0 throws Missing handlerUrl in Alinea config from alinea dev, alinea build and your site. Set it to the route that exports createHandler:

cms.ts
// 1.7
export const cms = createCMS({
  schema,
  workspaces,
  baseUrl,
  dashboardFile: 'admin.html'
})

// 2.0
export const cms = createCMS({
  schema,
  workspaces,
  baseUrl,
  handlerUrl: '/api/cms',
  adminPath: '/admin'
})

The handler now matches its path exactly, so requests have to use the configured URL (a trailing slash no longer matches).

baseUrl is required for production

Your site reaches the handler at handlerUrl resolved against baseUrl, also in production, to check for new content. Without a production baseUrl (and with a relative handlerUrl), alinea build exits and queries throw Missing baseUrl in Alinea config: set baseUrl.production to the url of your site. Alinea doesn't fall back to the request origin or to hosting provider variables: set the production URL of your site yourself, for example from an environment variable you define:

cms.ts
export const cms = createCMS({
  schema,
  workspaces,
  baseUrl: {
    development: 'http://localhost:3000',
    production: process.env.SITE_URL ?? 'https://example.com'
  },
  handlerUrl: '/api/cms'
})

dashboardFile is replaced by adminPath

adminPath is the path the dashboard is served on, /admin by default. alinea build writes the dashboard to public/admin.html and withAlinea serves it at /admin. dashboardFile still works when adminPath isn't set, but it is deprecated. See Configuration for the new maxUploadSize and tracer options.

syncInterval is a fallback

Deployed sites now check whether the content in the repository changed (by its commit sha) and sync right away when it did, which is what makes instant publishing work. syncInterval from your config is used as the fallback interval and defaults to 60 seconds. 0 syncs on every query, and passing disableSync: true to a query turns syncing off for it.

Media URLs

Image and file links now point to a route on your site instead of the file in public/. The src of an image link and the url/href of a file link used to be the stored location, such as /media/landscape.2V4c….jpg. In 2.0 they are the media entry's url: /admin/file/landscape.jpg?v=…, below your adminPath.

withAlinea rewrites ${adminPath}/file/* to your handler, which looks up the file and serves it. It also adds an images.localPatterns entry so next/image accepts these URLs. When a file is moved or renamed, its old URL keeps working through an alias.

What to check:

  • Your Next.js config is wrapped in withAlinea and your scripts run through alinea dev -- and alinea build --, which pass it the adminPath and handlerUrl. Without them media URLs return 404.

  • Media requests now reach your handler route. A static export without the handler can't serve them.

  • If you defined images.localPatterns or remotePatterns yourself, check that the admin file route is still allowed. The uploads.alinea.cloud remote pattern is no longer added.

  • Don't change the mediaDir of an existing workspace: stored locations are relative to it. New projects default to public/media.

  • A media file whose location is a url (some 1.x saves wrote the upload url there) can't be served. alinea build warns about these files; alinea build --fix points them at the file of the same name in the mediaDir when there is one.

Image links only have src: the url property, which held the same value, was removed so that spreading an image into <img> or next/image (<Image {...image} />) doesn't put a url attribute on the element. Replace image.url with image.src. File links keep url and href.

Don't derive media URLs from the stored file. Code that reads location, or parses the 1.x file names (name.<id>.ext) to build a URL or find an id, breaks on /admin/file/... URLs. Use the URL Alinea returns instead: src for images, url (or href) for files, and _url when you query media files directly:

import {cms} from '@/cms'
import {Query} from 'alinea'
import {MediaFile} from 'alinea/core'

// 1.7: built the url from the stored location
// const src = file.location

const files = await cms.find({
  type: MediaFile,
  select: {title: Query.title, url: Query.url}
})
// Without a select each result has its url as `_url`

ImageLink no longer needs a type parameter when the image field has no extra fields: replace ImageLink<undefined> with ImageLink.

A workspace can set mediaUrl to add a prefix to its media URLs, which helps when several workspaces have files with the same name.

Content and schema

Content files don't change format: entries, rich text, links and list rows written by 1.7 are read as they are. New properties are added when an entry is saved again (see below).

Config.media takes options

The media root now takes the same options as other roots. Children move to children:

// 1.7
media: Config.media({uploads: Config.page(...)})

// 2.0
media: Config.media({children: {uploads: Config.page(...)}})

A 1.7 call with children is silently read as options, so its children disappear. The media root also accepts i18n, which translates the alt text of media files.

Field.metadata has no options

Field.metadata(label) no longer takes inferTitleFrom, inferDescriptionFrom or inferImageFrom. The metadata field now also stores the URL aliases of the entry and audit fields: createdAt, createdBy, updatedAt and updatedBy, with the name and email of the editor. updatedAt and updatedBy are filled in when an entry is saved, createdAt and createdBy only when an entry is created, so they stay empty for existing entries. Keep that in mind for public repositories. The description is limited to 160 characters.

Other field changes

  • Field.time no longer has a step option.

  • Field.file pickers now also show images.

  • Field.entry.multiple no longer allows the same entry twice by default, pass allowDuplicates: true to keep the 1.7 behavior.

  • Date fields are displayed as day-month-year in the dashboard. The stored value is still an ISO date.

  • Trackers from Config.track.options must return their value synchronously, and Config.track.value was removed.

  • Options trackers type get(field) by the field, so a single link field reads as possibly null. Calls that pass the value type, eg. get<string>(field), no longer compile: pass the field only.

  • Queried links have the label the editor gave them as label. _label still holds the same value but is deprecated.

Rich text extensions and toolbars

The rich text editor moved to Tiptap 3, so custom extensions must be Tiptap 3 compatible. extensions is now a function that receives the default extensions, instead of an object that replaced them:

// 1.7
Field.richText('Body', {
  extensions: {...myExtensions}
})

// 2.0
Field.richText('Body', {
  extensions: defaults => ({...defaults, ...myExtensions})
})

defaultToolbar(enableTables) became defaultToolbar({enableTables, enableImages}), and toolbar button icons are components (or elements) instead of nodes. The toolbar presets, defaultToolbar, the ToolbarButton type and the default extensions are exported from alinea/field/richtext (alinea/field/richtext/Toolbar still works).

The RichText renderer from alinea/ui always renders tables with a <tbody>, and the tbody view override is gone.

Attributes that a custom extension adds to a node only reach your views and tag overrides of RichText as data-* attributes: render them as data-* in the extension's renderHTML. Content saved by 1.7 gets these attributes when it is saved again, see Custom attributes.

Edit.move

// 1.7
Edit.move({id, after: siblingId})

// 2.0
Edit.move({id, target: siblingId, dropPosition: 'after'})

dropPosition is 'after', 'before' or 'on' (move into the target), and targetType: 'root' moves an entry to the top of a root.

What changes when you save

The first save of an entry in 2.0 can produce a larger diff than you expect: missing field defaults are filled in (also in list rows), the metadata audit fields are added and media files gain an alt field. To normalize all files at once instead of entry by entry, run alinea build --fix and commit the result.

Handler and backend

Commit hooks replace entry hooks

The beforeCreate, afterUpdate, … hooks of 1.7 were declared but never called. They are replaced by two hooks that run for every commit, whatever it contains:

app/(alinea)/api/cms/route.ts
import {cms} from '@/cms'
import {createHandler} from 'alinea/next'
import {revalidateTag} from 'next/cache'

const handler = createHandler({
  cms,
  beforeCommit({mutations}) {
    // Inspect or rewrite the changes, return the mutations to commit
    return mutations
  },
  afterCommit({entries, removed}) {
    // Pages that query content refresh on their own, revalidate your own
    // caches, eg. a feed that lists products
    const changed = [...entries, ...removed]
    if (changed.some(entry => entry.type === 'Product'))
      revalidateTag('products', 'max')
  }
})

export const GET = handler
export const POST = handler

afterCommit receives the mutations, the sha of the new commit, the user, the changed entries as they are after the commit and the removed entries with the url they had. Errors thrown in it are logged and don't fail the commit. See Instant publishing.

remote is replaced by backend

The remote option of createHandler was removed. Pass a backend: the options object from 1.7 (database, auth, oauth2, github) still works unchanged, and it now also takes uploads: {s3}. You can also compose a backend from parts exported by the new alinea/backend entry, which replaces deep imports such as alinea/backend/api/CreateBackend:

import {auth, createBackend, database, github, uploads} from 'alinea/backend'

const backend = createBackend(
  database({driver: '@vercel/postgres', client: db}),
  auth.basic(
    (username, password) =>
      username === process.env.ALINEA_USERNAME &&
      password === process.env.ALINEA_PASSWORD
  ),
  github({/* the github options from 1.7 */}),
  uploads.s3({/* bucket and credentials */})
)

const handler = createHandler({cms, backend})

Self-hosted backends

  • OAuth2: validateClaims is now required, the backend refuses to start without it. Check at least the issuer and audience of the token there.

  • GitHub: the author option was removed. Commits get a Co-authored-by trailer for the signed-in editor instead.

  • Custom auth implementations: authenticate receives a second options argument.

  • Database: new alinea_user and alinea_user_role tables are created automatically on first use (on Postgres with row level security enabled). Drafts are no longer stored in the database, the 1.7 alinea_draft table is not used anymore.

Dashboard

The dashboard was rebuilt on React Aria Components. Nothing changes for editors beyond a new interface, but code that extends the dashboard needs updating.

Components

alinea/ui now only exports the RichText renderer and the imageBlurUrl helper (and the deprecated HStack/VStack, use Stack from alinea/components). Its Button, Chip, Icon, Loader, Typo and other components were removed, as were the files behind deep imports like alinea/ui/Button. Use the public component library instead, it is what the dashboard itself is built from:

// 1.7
import {Button, Loader} from 'alinea/ui'

// 2.0
import {Button, Spinner} from 'alinea/components'

See Components. Dashboard icons are available from alinea/dashboard/icons.

Theme tokens

The CSS custom properties of 1.7 were renamed and many were removed. Styles that read an old token silently fall back to the property's default. The closest replacements:

  • --alinea-background → --alinea-bg, --alinea-content → --alinea-backdrop, --alinea-lift, --alinea-inner and --alinea-toolbar → --alinea-bg-muted.

  • --alinea-foreground → --alinea-fg, --alinea-foreground-faded → --alinea-fg-muted, --alinea-title-foreground → --alinea-fg-strong.

  • --alinea-outline and --alinea-inner-outline → --alinea-border, --alinea-highlight → --alinea-muted.

  • --alinea-fields → --alinea-input, --alinea-fields-foreground → --alinea-field-label, --alinea-fields-focus and --alinea-focus-foreground → --alinea-ring.

  • --alinea-selected stays, --alinea-selected-foreground → --alinea-selected-fg, --alinea-selected-faded → --alinea-primary-subtle.

  • --alinea-button-background → --alinea-primary, --alinea-button-foreground → --alinea-primary-fg, --alinea-error → --alinea-danger.

  • --alinea-accent (the workspace color) → --alinea-workspace-color.

  • --alinea-variant-info-* → --alinea-primary-subtle and --alinea-primary-subtle-fg, --alinea-variant-success-* → --alinea-success-subtle(-fg), --alinea-variant-progress-* → --alinea-warning-subtle(-fg).

  • --alinea-modal-background → --alinea-scrim, --alinea-shadow → --alinea-shadow-raised, --alinea-border-radius → --alinea-radius.

  • Removed without a replacement: --alinea-hue, --alinea-saturation, --alinea-positive, --alinea-negative, --alinea-button-hover, --alinea-accent-foreground, --alinea-divider-top, --alinea-divider-bottom, --alinea-tabs-trigger-*, --alinea-fields-table, --alinea-fields-header, --alinea-fields-shadow, --alinea-fields-selected and the create and disabled variants. Derive hover and disabled shades with color-mix() and opacity.

The tokens of alinea/css, and its resets, now apply inside elements with a data-alinea-theme attribute only. The dashboard sets it on <html>, so the CSS of your dashboard views reads the tokens as before. A page of your site that imports alinea/css to render alinea/components needs an element with data-alinea-theme around them. See Theme tokens for the full list.

Custom field views

Field views are still referenced by path (view: '@/fields/Range.view') or passed as a component. The hooks and helpers for custom views now come from one entry point, alinea/cms. From alinea/dashboard, useField and its related hooks still work but are deprecated: the new useField returns a [value, setValue] tuple, and the options and error have their own hooks:

// 1.7
import {useField} from 'alinea/dashboard'
const {value, mutator, options, error} = useField(field)

// 2.0
import {useField, useFieldError, useFieldOptions} from 'alinea/cms'
const [value, setValue] = useField(field)
const options = useFieldOptions(field)
const error = useFieldError(field)

useFieldValue, useFieldOptions, useFieldError and useFieldKey move to alinea/cms too and useFieldMutator becomes useFieldSetter. Deep imports of dashboard hooks move as well: useLocale and useGraph from alinea/dashboard/hook/* are exported from alinea/cms, and useEntryEditor is replaced by useEntry. useEntryEditor still works as a shim for views that only read the entry: its activeVersion has the id, locale, path, status, title and type of the entry, and activeVersion.data only has path. Reading another property throws, read field values with useFieldValue(field) instead. alinea/dashboard/hooks is internal now. InputLabel is now an alias of the Field component: it takes label, description, error, required, disabled, readOnly, icon and shared. Its 1.7 props help, width, inline, size and the fold props are gone, so help text passed through {...options} is no longer shown: pass it as description, or replace it with FieldChrome from alinea/cms, which reads the label, help text and error from the field. The form atoms (useForm, FormProvider, FormRow and so on) were removed from alinea/dashboard. See Custom fields for a complete example.

Custom type views

A type's view now only receives {type}, the editor prop of 1.7 is gone. The view no longer replaces the whole editor: it renders below the entry header, which publishes and saves drafts, and reads and writes the fields of the entry with the hooks of alinea/cms. A custom auth view in the config is not used: the dashboard always renders its own sign-in.

List overviews

The lists of children are configured on the parent with the new overview option. summaryRow and summaryThumb views are no longer rendered, and orderChildrenBy and the overview: true field option are deprecated:

schema/Blog.ts
import {Config, Field} from 'alinea'

export const BlogPost = Config.document('Blog post', {
  // 1.7: summaryRow and summaryThumb views
  fields: {
    cover: Field.image('Cover'),
    // 1.7: Field.date('Publish date', {overview: true})
    publishDate: Field.date('Publish date')
  }
})

export const Blog = Config.document('Blog', {
  contains: ['BlogPost'],
  fields: {},
  overview: {
    columns: {
      publishDate: Config.column({
        header: 'Published',
        select: BlogPost.publishDate
      })
    },
    // 1.7: orderChildrenBy: {desc: BlogPost.publishDate}
    sort: {desc: BlogPost.publishDate},
    thumbnail: BlogPost.cover
  }
})
  • summaryRow: define the columns with overview.columns.

  • summaryThumb: set the card image with overview.thumbnail. By default cards show the first image found in the entry's fields.

  • orderChildrenBy: still works, move it to overview.sort.

  • overview: true on a field: still shows the field as a column, but only while the parent has no overview.columns.

See Overviews for sorting, custom cells and toolbar actions.

Other removed entry points

alinea/yjs and alinea/cloud/view/CloudAuth no longer exist. alinea/picker/entry/EntryPicker and alinea/picker/url/UrlPicker no longer ship the picker UI: EntryPickerModal, UrlPickerForm and UrlPickerModal were removed without a public replacement. Import the picker option types (EditorInfo, EditorLocation, EditorLimitLocation and EntryPickerConditions) from alinea/field/link. Code that subclassed fields relied on the removed shape system (alinea/core/Shape, Field.shape, Type.shape): the field constructors no longer take a shape, and postProcess became queryValue.

From a 2.0 preview

Projects on a 2.0 preview or release candidate have most of the above already. These changes landed in the release candidates:

  • Image links no longer have url, use src. File links keep url and href.

  • useEntry() from alinea/cms returns a DashboardEntry: the id, type, title, path, url, locale, status, workspace, root and parentId of the entry and its saved field values in data. The other properties of the internal entry row are gone.

  • useEntryEditor(): the publish status moved from activeVersion.data.status to activeVersion.status. Reading another property of activeVersion.data than path throws.

  • useSiblingFieldValue(key) is deprecated: pass the field to useFieldValue(field), which is typed and also reads fields of a parent row or the entry, or its key: useFieldValue('path'). EditFields takes an object field to render its fields in its scope.

  • Theme tokens apply inside data-alinea-theme only, see Theme tokens above. The workspace color is --alinea-workspace-color.

  • Select from alinea/components only shows its clear button with clearable. Field.select still lets editors clear fields that aren't required.

  • Select, ComboBox and MultipleSelect values are strings or numbers, and onValueChange is typed like the value you pass. Without a value, it receives string | number.

  • TimeField with a name submits 14:30 (or 14:30:15 with granularity="second") like a native time input, it used to submit seconds always.

  • NumberField no longer groups digits: pass formatOptions={{useGrouping: true}} to show 1,250.

  • afterCommit also receives the changed entries and the removed entries, so hooks no longer have to look them up from the mutations.

  • Every field accepts width, custom fields don't need to declare it in their options.

  • alinea build accepts an absolute handlerUrl without a production baseUrl, and its error names the missing baseUrl setting.

  • A type's view renders below the entry header, in the editor of the entry: the field hooks of alinea/cms and EditField edit its fields and the header publishes them. It used to replace the whole editor without access to the fields.

And these after the second release candidate:

  • Queried links have the label the editor gave them as label. _label still holds the same value but is deprecated.

  • Options trackers type get(field) by the field, so a single link field reads as possibly null. Calls that pass the value type, eg. get<string>(field), no longer compile: pass the field only.

  • Field.link takes kinds, eg. kinds: ['entry', 'url'], to limit the links editors can pick. Stored links of a kind the field no longer offers are left out when queried.

  • Titles sort regardless of case, accents and leading punctuation, with numbers by their value. The local content database is rebuilt once after upgrading.

  • The title and path of media files are required.

  • An option of an overview filter can leave out filter: it then lists every entry and is picked while no other option of its filter is.

  • Rich text toolbar buttons take hidden, and the links group has a Remove link button shown while the selection is in a link. Custom toolbars that copy the links group get it too.

After upgrading

Run your build and open the dashboard. Things to try: an image renders on your site through /admin/file/..., publishing an entry updates the site, and custom fields still render. Then have a look at what's new in 2.0: Field.localised for per-field translations, URL aliases and backlinks, instant publishing and the MCP server for coding agents.