@olmocms/front

Shared utilities, React components, SEO helpers, middleware, and CLI scaffold tool for Olmo CMS Next.js frontends.

Table of contents

• Package entries
• Installation
• Local development (watch mode)
• Releasing a new version
• CLI — olmo-front
• Entry point reference

Package entries

| Entry | What it exports | |---|---| | @olmocms/front | Re-exports everything | | @olmocms/front/client | getting() — typed API fetch helper | | @olmocms/front/seo | setSeoData() — maps Olmo API SEO payload to Next.js Metadata | | @olmocms/front/jsonld | buildBreadcrumb() and other JSON-LD schema builders | | @olmocms/front/middleware | olmoMiddleware() — injects x-current-path header + handles locale redirect | | @olmocms/front/components | GtmPage, JsonLd — shared React components |

Installation

npm install @olmocms/front

No registry configuration needed — the package is public on npm.

Local development (watch mode)

Use this workflow when you are actively developing @olmocms/front and want changes to reflect immediately in the consuming Next.js project.

Step 1 — Link the package locally

In the consuming project's package.json, use a local file: reference:

"dependencies": {
  "@olmocms/front": "file:../olmo-front"
}

Then run:

npm install

Step 2 — Start the watch build

In olmo-front/:

npm run dev

This runs tsup --watch, which rebuilds dist/ on every file change (ESM + CJS + type declarations).

Step 3 — Start the consuming project

In front.olmo/ (or any project consuming the package):

npm run dev

Next.js will pick up changes from dist/ on the next page reload. A full npm run dev restart is sometimes needed after major structural changes (e.g. adding a new entry point).

Switching back to the published version

When done developing and after publishing a new version:

"@olmocms/front": "^0.1.0"

Then run npm install.

Releasing a new version

Releases are automated by GitLab CI: pushing a vX.Y.Z git tag triggers npm publish to the public npm registry. You do not run npm publish manually for normal releases.

Day-to-day release flow

From a clean working tree on main:

npm version patch   # or minor / major — bumps package.json AND creates a vX.Y.Z git tag
git push origin main --follow-tags

That's the whole release. GitLab CI then:

1. Runs typecheck and build on every push (see .gitlab-ci.yml).
2. On a tag matching ^v\d+\.\d+\.\d+$, runs the publish job, which writes NPM_TOKEN into ~/.npmrc and runs npm publish. publishConfig.access: "public" in package.json makes it a public scoped publish.

Watch the pipeline at GitLab → CI/CD → Pipelines. When green, verify on https://www.npmjs.com/package/@olmocms/front.

Version bump rules

Follow semantic versioning (MAJOR.MINOR.PATCH):

| Change | Bump | Example | |---|---|---| | Breaking API change | MAJOR | 0.x.x → 1.0.0 | | New entry point or new export | MINOR | 0.1.0 → 0.2.0 | | Bug fix, internal refactor | PATCH | 0.1.0 → 0.1.1 |

npm rejects re-publishing an existing version, so always bump first.

One-time setup (reference — already done)

Kept here so the wiring is recoverable if the project is ever cloned fresh or the token rotates:

• npm.js org — the @olmocms organization owns the scope on npmjs.com.
• npm automation token — generated under Account → Access Tokens → Generate New Token → Granular Access Token (or a classic Automation token), scoped to publish @olmocms/*. Automation tokens bypass 2FA, which CI requires.
• GitLab CI/CD variable — token stored as NPM_TOKEN under Settings → CI/CD → Variables, marked Masked and Protected.
• GitLab protected tag — v* added under Settings → Repository → Protected tags, so only protected refs can read NPM_TOKEN.
• .gitlab-ci.yml — defines typecheck, build, and the tag-gated publish job.

Manual publish (fallback only)

Only needed for the very first publish of a new scope or if CI is broken:

npm login
npm run build
npm publish

CLI — olmo-front

The package ships a CLI binary installed as olmo-front.

Usage

npx olmo-front init

What it scaffolds

The init command creates the standard src/app/[locale]/ route structure for a new Olmo Next.js project:

src/
  app/
    [locale]/
      (website)/
        page.tsx          ← Home
        content.tsx
        layout.tsx
        contatti/
        lavora-con-noi/
        news/
          [slug]/
        prodotti/
          [slug]/
        case-studies/
          [slug]/
        cookie-policy/
  components/
    Header/
      Header.tsx
    Footer.tsx
    Form/
      Contact.tsx
      Newsletter.tsx
      Workwithus.tsx
  i18n/
    navigation.ts
    routing.ts
  types.d.ts

Scaffold files are minimal stubs that import from @olmocms/front and follow the boilerplate conventions.

Entry point reference

@olmocms/front/client

import { getting } from '@olmocms/front/client'

const data = await getting<MyType>(locale, pathname, 'page')

getting(locale, path, type?) — fetches from the Olmo API using NEXT_PUBLIC_API_URL. Returns the typed response or null on error. Adds the x-api-key header from NEXT_PUBLIC_API_KEY.

@olmocms/front/seo

import { setSeoData } from '@olmocms/front/seo'

const metadata = setSeoData({ seo: page.seo, route: page.route })

Maps the Olmo API SEO payload to a Next.js Metadata object ready to return from generateMetadata().

@olmocms/front/jsonld

import { buildBreadcrumb } from '@olmocms/front/jsonld'

buildBreadcrumb([
  { name: 'Home', url: 'https://example.com/it/' },
  { name: 'News', url: 'https://example.com/it/news/' },
  { name: 'Article title', url: 'https://example.com/it/news/article/' },
])

Returns a BreadcrumbList JSON-LD schema object. Pass it to <JsonLd schema={...} />.

@olmocms/front/middleware

import { olmoMiddleware } from '@olmocms/front/middleware'
export default olmoMiddleware(routing)

Wraps next-intl routing middleware and injects the x-current-path header into every request so Server Components can read the current URL without usePathname().

@olmocms/front/components

import { GtmPage, JsonLd } from '@olmocms/front/components'

<GtmPage slug={pathname} lang={locale} name={page.name} template={page.template} />
<JsonLd schema={buildBreadcrumb([...])} />

• GtmPage — fires a virtual_pageview event to window.dataLayer on mount.
• JsonLd — renders a <script type="application/ld+json"> tag with the given schema.

Environment variables

| Variable | Required | Description | |---|---|---| | NEXT_PUBLIC_API_URL | Yes | Base URL of the Olmo API (e.g. https://api.example.com) | | NEXT_PUBLIC_API_KEY | Yes | API key sent as x-api-key header | | NEXT_PUBLIC_BASE_URL | Yes | Public URL of the frontend (used in canonical URLs, JSON-LD) | | NEXT_PUBLIC_GTM_ID | No | Google Tag Manager container ID | | NEXT_PUBLIC_RECAPTCHA_KEY | No | reCAPTCHA v3 site key (required if using contact/newsletter forms) |