alinea 2.0.0-preview.9 → 2.0.0-rc2

package/docs/query/structural.md

@@ -0,0 +1,165 @@
+# Structural
+
+Most queries start by saying which entries you want: of a type, at a url, in a root, in a locale. Then you choose what to get back and in which order. This page covers both; to match on field values see [Filtering](filtering.md).
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+import {Query} from 'alinea'
+
+const posts = await cms.find({
+  type: BlogPost,
+  root: cms.workspaces.main.pages,
+  locale: 'en',
+  select: {title: Query.title, url: Query.url},
+  orderBy: {desc: BlogPost.publishDate},
+  take: 10
+})
+```
+
+## Selecting entries
+
+- `type`: a type, or an array of types to match any of them: `type: [Page, BlogPost]`. It also narrows the result type.
+- `id`: the entry id.
+- `url`: the entry's url, for example `'/blog/hello-world'`. Handy in a catch-all route.
+- `path`: the entry's path, the last segment of its url.
+- `parentId`: the id of the parent entry. `null` matches entries at the top of a root.
+- `level`: the depth in the tree. `0` is the top of a root, `1` their children, and so on.
+- `workspace` and `root`: a name, or the object from your CMS instance: `cms.workspaces.main`, `cms.workspaces.main.pages`.
+- `location`: a workspace, a root or a seeded page. With a seeded page, such as `cms.workspaces.main.pages.blog`, it matches the entries below it.
+- `alias`: a previous url stored in the entry's [metadata aliases](../schema/document.md), to redirect old urls.
+- `createdAt` and `updatedAt`: the audit timestamps of documents, in Unix seconds.
+
+`id`, `url`, `path`, `parentId`, `level`, `alias`, `createdAt`, `updatedAt`, `workspace` and `root` take a value or a condition with the [operators](filtering.md) from filters:
+
+```tsx
+import {cms} from '@/cms'
+import {Query} from 'alinea'
+
+// Several ids
+await cms.find({id: {in: ['2g8FtR', '2g8FtS']}})
+
+// Everything below /docs
+await cms.find({url: {startsWith: '/docs/'}})
+
+// Top-level entries of a root, for a main menu
+await cms.find({
+  root: cms.workspaces.main.pages,
+  level: 0,
+  select: {title: Query.title, url: Query.url}
+})
+
+// Entries below a seeded page
+await cms.find({location: cms.workspaces.main.pages.blog})
+```
+
+## Locales
+
+In a root with [i18n](../internationalization.md), every translation is a separate entry version. Without a `locale`, a query matches all of them, so `find` returns an entry once per language and `first` returns whichever comes first.
+
+- `locale`: only entries in this locale (compared case-insensitively). `null` matches entries in roots without i18n.
+- `preferredLocale`: entries in this locale plus entries without a locale. Use it when a query spans translated and untranslated roots.
+
+```tsx
+import {cms} from '@/cms'
+import {Query} from 'alinea'
+
+export async function pageByUrl(locale: string, slug: Array<string>) {
+  return cms.first({
+    locale,
+    url: `/${[locale, ...slug].join('/')}`,
+    select: {title: Query.title, type: Query.type}
+  })
+}
+```
+
+## Status
+
+`status` chooses between published, draft and archived versions:
+
+- `'published'` (default): only published entries.
+- `'draft'` or `'archived'`: only drafts, or only archived entries.
+- `'preferDraft'`: one version per entry: the draft if there is one, then the published version, then the archived one.
+- `'preferPublished'`: one version per entry: the published one if there is one, then the archived one, then the draft.
+- `'preview'`: what a preview shows, like `preferDraft` without archived entries. An archived entry that is being previewed shows as published. This is the default in Next.js draft mode.
+- `'all'`: every version, so an entry can appear more than once.
+
+Relations inside the query use the same status.
+
+## Choosing what to return
+
+- `select`: the fields and properties to return, in any shape. A single expression, such as `select: Query.url`, returns plain values. See [What a query returns](../query.md).
+- `include`: extra values to add to the full entry, typically [related entries](related.md). It only applies when there's no `select`; with a `select`, put everything in the select.
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+import {Query} from 'alinea'
+
+// All fields of the post, plus its parent
+const post = await cms.get({
+  type: BlogPost,
+  path: 'hello-world',
+  include: {
+    blog: Query.parent({select: {title: Query.title, url: Query.url}})
+  }
+})
+
+// Only what the card needs
+const card = await cms.get({
+  type: BlogPost,
+  path: 'hello-world',
+  select: {
+    title: Query.title,
+    intro: BlogPost.intro,
+    blog: Query.parent({select: {title: Query.title, url: Query.url}})
+  }
+})
+```
+
+## Sorting and pagination
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+import {Query} from 'alinea'
+
+const page = 2
+const perPage = 10
+
+const posts = await cms.find({
+  type: BlogPost,
+  select: {title: Query.title, url: Query.url},
+  orderBy: [
+    // Newest first
+    {desc: BlogPost.publishDate},
+    // Same date: alphabetical
+    {asc: Query.title}
+  ],
+  skip: (page - 1) * perPage,
+  take: perPage
+})
+```
+
+- `orderBy`: one `{asc: ...}` or `{desc: ...}`, or an array to break ties. Pass a field or a `Query` property. Text is compared case-insensitively unless you add `caseSensitive: true`, and entries without a value come last in both directions.
+- Without `orderBy`, entries come in their stored order: the order of siblings in the sidebar. Queries with `search` are ordered by relevance.
+- `skip` and `take`: skip a number of results and return at most `take`. Both must be whole numbers of 0 or more. For the total, run `cms.count` with the same options but without `skip` and `take`.
+
+## One entry per value
+
+`groupBy` keeps one entry for every distinct value of a field or property: the first match in stored order, or the most relevant one when searching. Sorting and pagination apply afterwards, to the remaining entries.
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+import {Query} from 'alinea'
+
+// The first post of every blog
+const firstPosts = await cms.find({
+  type: BlogPost,
+  groupBy: Query.parentId,
+  select: {title: Query.title, url: Query.url}
+})
+```
+
+`groupBy` takes a single field. Because the entry for each value is picked before sorting, it can't give you "the newest post per blog", and it doesn't return lists of entries per value: for those, query the entries and group them in your own code. Group on plain values such as text, select or date fields; link fields store a unique id per link, so they don't group.

package/docs/query.md

@@ -0,0 +1,190 @@
+# Querying content
+
+Read content with the methods on your CMS instance. Queries are plain objects, typed from your schema, and run on the server: in server components, route handlers, `generateMetadata` and `generateStaticParams`. They read from a local copy of your content that ships with your deploy and is kept in sync when the content changes, see [Instant publishing](instant-publishing.md).
+
+File: app/page.tsx
+```tsx
+import {cms} from '@/cms'
+import {HomePage} from '@/schema'
+
+export default async function Page() {
+  const home = await cms.get({type: HomePage})
+  return <h1>{home.title}</h1>
+}
+```
+
+## Methods
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+
+// All matches, as an array (possibly empty)
+const posts = await cms.find({type: BlogPost})
+
+// The first match, or null
+const latest = await cms.first({
+  type: BlogPost,
+  orderBy: {desc: BlogPost.publishDate}
+})
+
+// The first match, or throws "Entry not found"
+const post = await cms.get({type: BlogPost, path: 'hello-world'})
+
+// The number of matches
+const total = await cms.count({type: BlogPost})
+```
+
+Use `first` when a missing entry is a normal case, such as a url that may not exist (call `notFound()` when it returns `null`), and `get` for entries that must exist, like a seeded home page.
+
+## What a query returns
+
+Without a `select`, you get the fields of the type you passed as `type`, plus the entry's own properties, prefixed with an underscore. A query without `type` returns only those properties.
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+
+const post = await cms.get({type: BlogPost, path: 'hello-world'})
+post.title // a field of the type
+post.publishDate // "2026-09-23"
+post.author // link fields are resolved: {title, url, ...} or null
+post._id // the entry id
+post._url // "/blog/hello-world"
+post._locale // "en", or null in roots without i18n
+```
+
+The entry properties are `_id`, `_type`, `_index`, `_workspace`, `_root`, `_status`, `_parentId`, `_locale`, `_path`, `_url`, `_createdAt` and `_updatedAt`.
+
+With `select` you get exactly what you ask for, in the shape you ask for. Select fields through the type (`BlogPost.publishDate`) and entry properties through `Query`:
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+import {Query} from 'alinea'
+
+const cards = await cms.find({
+  type: BlogPost,
+  select: {
+    title: Query.title,
+    url: Query.url,
+    date: BlogPost.publishDate,
+    cover: BlogPost.cover
+  }
+})
+// Array<{title: string, url: string, date: string, cover: ImageLink | null}>
+
+// A single expression returns plain values
+const urls = await cms.find({type: BlogPost, select: Query.url})
+// Array<string>
+```
+
+`Query` has `id`, `title`, `type`, `index`, `workspace`, `root`, `status`, `parentId`, `locale`, `path`, `url`, `aliases`, `createdAt` and `updatedAt`, plus the relation helpers such as `Query.children` and `Query.referencedBy` described in [Related content](query/related.md) and `Query.snippet` for [search results](query/filtering.md).
+
+### Query fields and type fields
+
+There are two kinds of references you can select. `Query.*` are the built-in properties every entry has, whatever its type: `Query.id`, `Query.title`, `Query.url` and the others above. The fields you define are selected through their type: `BlogPost.intro` is the `intro` field of `BlogPost`, `BlogPost.cover` its cover image. Type fields are typed from their definition and resolved like they are without a select, so `BlogPost.cover` returns an `ImageLink`. Combine both in one `select`:
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+import {Query} from 'alinea'
+
+const posts = await cms.find({
+  type: BlogPost,
+  select: {
+    // Built-in properties of the entry
+    id: Query.id,
+    title: Query.title,
+    url: Query.url,
+    // Fields of the BlogPost type
+    intro: BlogPost.intro,
+    cover: BlogPost.cover
+  }
+})
+// Array<{id: string, title: string, url: string, intro: string, cover: ImageLink | null}>
+```
+
+A type field only has a value on entries of that type, so select it in a query for that `type` (or one filtered on `_type`). `Query` fields work in any query, also one without a `type`, such as a search across all entries. Fields that `Config.document` adds, like `title` and `path`, are available both ways: `Query.title` and `BlogPost.title` return the same value.
+
+Fields inside an [object field](fields/object.md) are selected through the object: `Page.seo.title` returns the `title` of the `seo` object, typed like the field. That works wherever a field can be selected, also inside relations such as `Query.children`, and in `orderBy`:
+
+```tsx
+import {cms} from '@/cms'
+import {Config, Field, Query} from 'alinea'
+
+export const Page = Config.document('Page', {
+  fields: {
+    seo: Field.object('SEO', {
+      fields: {
+        title: Field.text('SEO title'),
+        description: Field.text('SEO description')
+      }
+    })
+  }
+})
+
+const pages = await cms.find({
+  type: Page,
+  select: {url: Query.url, title: Page.seo.title},
+  orderBy: {asc: Page.seo.title}
+})
+// Array<{url: string, title: string}>
+```
+
+Selecting only what a page needs keeps the data you pass to client components small, and TypeScript infers the result either way. To name the type of a result, use `Awaited<ReturnType<typeof yourQueryFunction>>`.
+
+## Query options
+
+- Which entries: `type`, `id`, `path`, `url`, `parentId`, `workspace`, `root`, `location`, `level`, `locale`, `status` and more, see [Structural queries](query/structural.md).
+- Matching content: `filter` on field values and `search` for full text, see [Filtering](query/filtering.md).
+- Shape and order: `select`, `include`, `orderBy`, `groupBy`, `skip` and `take`, see [Structural queries](query/structural.md).
+- Related entries: parents, children, siblings, translations and linked entries in the same query, see [Related content](query/related.md).
+
+Options you pass as `undefined` are ignored, which makes it easy to build a query from optional parameters.
+
+## Drafts and previews
+
+Queries return published content by default. When Next.js draft mode is on, for example while an editor looks at a [live preview](live-previews.md), Alinea switches to drafts where they exist and applies the unsaved changes of the preview, without any change to your queries. Pass `status` to override this.
+
+## Example schema
+
+The examples in this chapter use this schema:
+
+File: schema.ts
+```tsx
+import {Config, Field} from 'alinea'
+
+export const Author = Config.document('Author', {
+  fields: {
+    avatar: Field.image('Avatar'),
+    bio: Field.text('Bio', {multiline: true})
+  }
+})
+
+export const Category = Config.document('Category', {fields: {}})
+
+export const Blog = Config.document('Blog', {
+  contains: ['BlogPost'],
+  fields: {}
+})
+
+export const BlogPost = Config.document('Blog post', {
+  fields: {
+    publishDate: Field.date('Publish date'),
+    intro: Field.text('Intro', {multiline: true, searchable: true}),
+    featured: Field.check('Featured'),
+    cover: Field.image('Cover image'),
+    author: Field.entry('Author', {condition: {_type: 'Author'}}),
+    categories: Field.entry.multiple('Categories', {
+      condition: {_type: 'Category'}
+    }),
+    tags: Field.select.multiple('Tags', {
+      options: {news: 'News', release: 'Release', tutorial: 'Tutorial'}
+    }),
+    body: Field.richText('Body', {searchable: true})
+  }
+})
+```
+
+Structural (query/structural.md)

package/docs/quickstart.md

@@ -0,0 +1,203 @@
+# Quickstart
+
+Add Alinea to a Next.js project in a few steps. Prefer to let your coding agent do the work? Paste this prompt into Claude Code, Cursor or Codex and it follows the [AI-assisted setup guide](ai-setup.md).
+
+> Read https://v2.alineacms.com/start.md and help me add Alinea to my Next.js project
+
+## 1. Set up Next.js
+
+Create a new Next.js project in a directory of your choice. To add Alinea to an existing project, skip to step 2. Alinea's Next.js integration uses the App Router and requires Node.js 24 or higher and React 19.
+
+```shellscript
+npx create-next-app@latest
+```
+
+Note (info): Read the full instructions in the [Next.js docs](https://nextjs.org/docs/getting-started/installation)
+
+## 2. Install Alinea
+
+Navigate to the newly created project directory and install the package with your preferred package manager.
+
+Variant: npm
+```shellscript
+npm install alinea@preview
+```
+
+Variant: yarn
+```shellscript
+yarn add alinea@preview
+```
+
+Variant: pnpm
+```shellscript
+pnpm add alinea@preview
+```
+
+Variant: bun
+```shellscript
+bun add alinea@preview
+```
+
+## 3. Initialize the project
+
+Alinea requires a [config file](configuration.md) which can be auto-generated by running `alinea init`. If you prefer plain JavaScript over TypeScript, rename the created file from `cms.ts` to `cms.js`.
+
+Variant: npm
+```shellscript
+npx alinea@preview init
+```
+
+Variant: yarn
+```shellscript
+yarn alinea init
+```
+
+Variant: pnpm
+```shellscript
+pnpm alinea init
+```
+
+Variant: bun
+```shellscript
+bun alinea init
+```
+
+In a Next.js project `alinea init` sets up everything the dashboard needs:
+
+- `cms.ts` (in `src/` if your project has a `src` directory) holds your schema, workspaces and settings such as `baseUrl`, `handlerUrl: '/api/cms'` and `adminPath: '/admin'`. The production `baseUrl` is read from `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`, which Vercel sets during the build. Replace it with the URL of your site when you deploy elsewhere.
+- `app/(alinea)/api/cms/route.ts` is the API route the dashboard talks to. It passes your `cms` to `createHandler` from `alinea/next`. It imports `@/cms`, so check that the `@/*` path alias in `tsconfig.json` points to the folder that holds `cms.ts`.
+- `content/pages/welcome.json` is a first entry. `content/media` holds the entries of the media library, the uploaded files themselves are written to `public/media` (the workspace's `mediaDir`).
+- The `dev` and `build` scripts in `package.json` are rewritten to run through Alinea: `next dev` becomes `alinea dev -- next dev` and `next build` becomes `alinea build -- next build`.
+- `/public/admin.html` and `/public/admin/` are added to `.gitignore`: `alinea build` writes the dashboard there.
+
+## 4. Adjust Next.js config
+
+Wrap your Next.js config with `withAlinea`. It serves the dashboard on your site at `adminPath`, forwards media file requests, and keeps the generated content package out of the server bundle:
+
+Variant: next.config.ts
+```tsx
+import {withAlinea} from 'alinea/next'
+import type {NextConfig} from 'next'
+
+const nextConfig: NextConfig = {
+  // Your Next.js options
+}
+
+export default withAlinea(nextConfig)
+```
+
+Variant: next.config.js
+```tsx
+const {withAlinea} = require('alinea/next')
+
+const nextConfig = {
+  // Your Next.js options
+}
+
+module.exports = withAlinea(nextConfig)
+```
+
+## 5. Start the dev server
+
+Congratulations, Alinea is now ready to boot! Start your dev script:
+
+Variant: npm
+```shellscript
+npm run dev
+```
+
+Variant: yarn
+```shellscript
+yarn dev
+```
+
+Variant: pnpm
+```shellscript
+pnpm dev
+```
+
+Variant: bun
+```shellscript
+bun run dev
+```
+
+The script runs `alinea dev -- next dev`: Alinea compiles `cms.ts`, starts its local server and then starts `next dev` with the settings `withAlinea` needs. Open the dashboard at [http://localhost:3000/admin](http://localhost:3000/admin) and have a look around.
+
+Note (info): Running `npx alinea dev` on its own only starts the local dashboard on http://localhost:4500, not your site. Keep the `alinea dev -- next dev` form in your dev script so both run together and the dashboard is served from your Next.js app. The same goes for `alinea build -- next build`, which generates your content before the site is built.
+
+## 6. Show content on a page
+
+The generated `Page` type only has a title. Add an image and a body to it in `cms.ts`, and export it so your pages can query it:
+
+File: cms.ts
+```tsx
+import {Config, Field} from 'alinea'
+
+// Export the type so your pages can query it
+export const Page = Config.document('Page', {
+  fields: {
+    cover: Field.image('Cover image'),
+    body: Field.richText('Body')
+  }
+})
+```
+
+Open the Welcome page in the dashboard, pick a cover image (upload one in the picker), write some text and publish. Then render it on your homepage by replacing `app/page.tsx`:
+
+File: app/page.tsx
+```tsx
+import {cms, Page} from '@/cms'
+import {RichText} from 'alinea/ui'
+import Image from 'next/image'
+import {notFound} from 'next/navigation'
+
+export default async function Home() {
+  const page = await cms.first({type: Page, path: 'welcome'})
+  if (!page) notFound()
+  return (
+    <main>
+      <h1>{page.title}</h1>
+      {page.cover && (
+        <Image
+          src={page.cover.src}
+          width={page.cover.width}
+          height={page.cover.height}
+          alt={page.cover.alt ?? ''}
+        />
+      )}
+      <RichText doc={page.body} />
+    </main>
+  )
+}
+```
+
+`cms.first` finds the entry stored in `content/pages/welcome.json` by its path, and passing `type: Page` types the result. An image field returns the `src`, dimensions and alt text `next/image` needs, and `withAlinea` allows these urls in your image config. See the [Image field](fields/image.md) for blur placeholders and focal points, and the [Rich text field](fields/rich-text.md) for rendering rich text with your own components.
+
+## 7. Enable live previews
+
+To see the page you are editing next to the editor, set `preview: true` in `cms.ts` (`alinea init` leaves it commented out) and render the preview component in your root layout:
+
+File: app/layout.tsx
+```tsx
+import {cms} from '@/cms'
+
+export default function RootLayout({children}: {children: React.ReactNode}) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <cms.previews widget />
+      </body>
+    </html>
+  )
+}
+```
+
+The `widget` prop adds a small toolbar to your pages to switch to the dashboard, read more in [Live previews](live-previews.md).
+
+## Next steps
+
+- Define your content types in the [schema](schema.md) and pick [fields](fields.md).
+- Render content in your pages with [queries](query.md).
+- Follow the [tutorial](tutorial.md) to build a complete site.
+- [Deploy](deploy.md) your site with a backend for publishing.

package/docs/reference.md

@@ -0,0 +1,3 @@
+# Reference
+
+Working with Alinea should feel intuitive but if you're looking for more in-depth information or feel like something is missing have a look here.