Skip to content
LogoLogo

Your first server-rendered page

In this tutorial we make a landing page in the Picked CMS and render it on your server. A search engine reads the content in the first response, and the browser takes over after that.

At the end you have one page layout, one content entry, and a server that returns your content in its HTML.

Before you start

  • A Picked project. Add Picked to your application makes one.
  • A server that renders React or Svelte and can add a script tag to its HTML.
  • Node 20 or later.

1. Model the page layout

A page layout sets which fields your page holds.

  1. Open your workspace.
  2. Click Pages in the sidebar, then Page Layouts.
  3. Click New model.
  4. Set Category to Page layout.
  5. Enter the name Page hero and the key page-hero. The key is stable, and your SDK code and your API calls both use it.
  6. Add a Single-line text field with the key title.
  7. Add a Markdown field with the key body.
  8. Click Create model.
A page layout in the schema builder on the Picked dashboard

Your layout now holds two fields. It holds no content yet.

2. Make the page and fill it

  1. Click Pages in the sidebar.
  2. Click New Experience.
  3. Choose the Page type.
  4. Choose your page-hero layout.
  5. Open the Properties tab.
  6. Enter a title and a body.
  7. Click Save. Picked makes a content entry and links it to the page.
  8. Correct every field error.

3. Publish the workspace

  1. Click Publish in the workspace toolbar.
  2. Click Publish to confirm.

Your content is now live. Read it back with curl, and put your own project ID in the path:

curl https://api.picked.app/api/v1/projects/proj_123

The answer holds your steps. Each one carries a layoutContentId, which points at the content entry behind it.

4. Make the snapshot on your server

serialize() finds which experiences match the URL and reads their content. It gives you a snapshot as plain JSON.

Make one client for each request, in server.ts:

import { createClient } from 'picked'
import { serialize } from '@picked/client/server'
 
const client = createClient(options)
 
const snapshot = await serialize(client, {
  projectConfig,
  attributes: { location: { pathname: url.pathname } },
})

Write the snapshot into your HTML answer:

const html = `
  <div id="root">${appHtml}</div>
  <script>window.__PICKED__ = ${JSON.stringify(snapshot)}</script>
`

5. Render the slot

<ExperienceSlot name="page" /> renders every experience that points at that slot. Give the provider your snapshot, so the first paint in the browser matches the HTML from your server.

Register the component under the same name that the page uses. Here it is CMSPage.

import type { CreateClientOptions } from 'picked'
import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
import { useStepContent } from '@picked/react/hooks'
 
function CMSPage() {
  const content = useStepContent()
  const title = typeof content?.title === 'string' ? content.title : ''
  return <h1>{title}</h1>
}
 
const options = {
  projectId: 'proj_123',
  components: { CMSPage: adaptReactComponent(CMSPage) },
  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
} satisfies CreateClientOptions
 
export function Page({ snapshot }) {
  return (
    <PickedProvider options={options} snapshot={snapshot}>
      <ExperienceSlot name="page" />
    </PickedProvider>
  )
}

Point your page experience at the slot. Set its target selector to .picked-slot-page, and publish again.

6. Check that a crawler can read it

  1. Read the answer from your server with curl, or with the view-source command of your browser.
  2. Find your title in the HTML.

Your title is in the first response, not in a script that the browser must run. A crawler and a social preview both read it.

What you built

You have a page whose content lives in the Picked CMS and whose HTML comes from your server. An editor changes the copy in the dashboard and publishes. Your server serves the new content on the next request, and you deploy nothing.

Where to go next