@majordigital/create-acorn 1.3.0 → 1.3.1

package/bin/create-acorn.mjs

@@ -224,9 +224,21 @@ async function setupStoryblok(projectName) {
   console.log('Setting up Storyblok...');
   console.log('');
 
-  // Install Storyblok SDK
-  console.log('Installing @storyblok/react...');
-  await runCommand('npm', ['install', '--legacy-peer-deps', '@storyblok/react']);
+  const spaceId = await ask('Enter your Storyblok Space ID');
+  if (!spaceId || !/^\d+$/.test(spaceId)) {
+    console.error('Space ID must be a numeric value (e.g. 338885). You can find it in your Storyblok dashboard.');
+    exit(1);
+  }
+  console.log('');
+
+  // Install Storyblok dependencies
+  console.log('Installing Storyblok dependencies...');
+  await runCommand('npm', ['install', '--legacy-peer-deps',
+    '@storyblok/react', '@storyblok/js', 'storyblok-js-client'
+  ]);
+  await runCommand('npm', ['install', '--save-dev', '--legacy-peer-deps',
+    'storyblok', 'storyblok-generate-ts'
+  ]);
   console.log('');
 
   // Update next.config.ts — replace Prismic image patterns with Storyblok
@@ -250,30 +262,24 @@ async function setupStoryblok(projectName) {
     console.log('Warning: Could not update next.config.ts image patterns.');
   }
 
-  // Create src/lib/storyblok.ts
-  const libDir = join(process.cwd(), 'src', 'lib');
-  writeFileSync(join(libDir, 'storyblok.ts'), `import { apiPlugin, storyblokInit } from '@storyblok/react/rsc';
-
-import Page from '@/components/storyblok/Page';
-import Feature from '@/components/storyblok/Feature';
-import Grid from '@/components/storyblok/Grid';
-import Teaser from '@/components/storyblok/Teaser';
-
-export const getStoryblokApi = storyblokInit({
-  accessToken: process.env.STORYBLOK_PREVIEW_TOKEN,
-  use: [apiPlugin],
-  components: {
-    page: Page,
-    feature: Feature,
-    grid: Grid,
-    teaser: Teaser,
-  },
-  apiOptions: {
-    region: 'eu',
-  },
-});
-`);
-  console.log('Created src/lib/storyblok.ts');
+  // Copy standardised Storyblok API layer from storyblok/storyblok-api/src/
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const storyblokSrcDir = join(__dirname, '..', 'storyblok', 'storyblok-api', 'src');
+
+  // Copy src/lib/storyblok/ (init, bloks, fetch, helpers, types, etc.)
+  const targetLibStoryblok = join(process.cwd(), 'src', 'lib', 'storyblok');
+  cpSync(join(storyblokSrcDir, 'lib', 'storyblok'), targetLibStoryblok, { recursive: true });
+  console.log('Copied Storyblok API layer (lib/storyblok/).');
+
+  // Copy src/lib/buildCache.ts
+  cpSync(join(storyblokSrcDir, 'lib', 'buildCache.ts'), join(process.cwd(), 'src', 'lib', 'buildCache.ts'));
+  console.log('Copied build cache utility (lib/buildCache.ts).');
+
+  // Copy src/ui/FallbackComponent.tsx
+  const targetUiDir = join(process.cwd(), 'src', 'ui');
+  mkdirSync(targetUiDir, { recursive: true });
+  cpSync(join(storyblokSrcDir, 'ui', 'FallbackComponent.tsx'), join(targetUiDir, 'FallbackComponent.tsx'));
+  console.log('Copied FallbackComponent (ui/FallbackComponent.tsx).');
 
   // Create StoryblokProvider
   const componentsDir = join(process.cwd(), 'src', 'components');
@@ -288,91 +294,16 @@ export default function StoryblokProvider({ children }: PropsWithChildren) {
   return children;
 }
 `);
-  console.log('Created src/components/StoryblokProvider.tsx');
-
-  // Create Storyblok component directory and base components
-  const sbComponentsDir = join(componentsDir, 'storyblok');
-  mkdirSync(sbComponentsDir, { recursive: true });
-
-  writeFileSync(join(sbComponentsDir, 'Page.tsx'), `import { storyblokEditable, StoryblokServerComponent } from '@storyblok/react/rsc';
-import type { SbBlokData } from '@storyblok/react/rsc';
-
-interface PageBlok extends SbBlokData {
-  body?: SbBlokData[];
-}
-
-export default function Page({ blok }: { blok: PageBlok }) {
-  return (
-    <main {...storyblokEditable(blok)}>
-      {blok.body?.map((nestedBlok) => (
-        <StoryblokServerComponent blok={nestedBlok} key={nestedBlok._uid} />
-      ))}
-    </main>
-  );
-}
-`);
-
-  writeFileSync(join(sbComponentsDir, 'Grid.tsx'), `import { storyblokEditable, StoryblokServerComponent } from '@storyblok/react/rsc';
-import type { SbBlokData } from '@storyblok/react/rsc';
-
-interface GridBlok extends SbBlokData {
-  columns?: SbBlokData[];
-}
-
-export default function Grid({ blok }: { blok: GridBlok }) {
-  return (
-    <div {...storyblokEditable(blok)} className="grid grid-cols-3 gap-6">
-      {blok.columns?.map((nestedBlok) => (
-        <StoryblokServerComponent blok={nestedBlok} key={nestedBlok._uid} />
-      ))}
-    </div>
-  );
-}
-`);
-
-  writeFileSync(join(sbComponentsDir, 'Feature.tsx'), `import { storyblokEditable } from '@storyblok/react/rsc';
-import type { SbBlokData } from '@storyblok/react/rsc';
-
-interface FeatureBlok extends SbBlokData {
-  name?: string;
-}
-
-export default function Feature({ blok }: { blok: FeatureBlok }) {
-  return (
-    <div {...storyblokEditable(blok)} className="feature">
-      <span>{blok.name}</span>
-    </div>
-  );
-}
-`);
-
-  writeFileSync(join(sbComponentsDir, 'Teaser.tsx'), `import { storyblokEditable } from '@storyblok/react/rsc';
-import type { SbBlokData } from '@storyblok/react/rsc';
-
-interface TeaserBlok extends SbBlokData {
-  headline?: string;
-}
-
-export default function Teaser({ blok }: { blok: TeaserBlok }) {
-  return (
-    <div {...storyblokEditable(blok)} className="teaser">
-      <h2>{blok.headline}</h2>
-    </div>
-  );
-}
-`);
-  console.log('Created Storyblok component boilerplate (Page, Grid, Feature, Teaser).');
+  console.log('Created StoryblokProvider component.');
 
   // Update layout.tsx to wrap with StoryblokProvider
   const layoutPath = join(process.cwd(), 'src', 'app', 'layout.tsx');
   try {
     let layout = readFileSync(layoutPath, 'utf-8');
-    // Add import
     layout = layout.replace(
       "import '@/styles/globals.css';",
       "import '@/styles/globals.css';\n\nimport StoryblokProvider from '@/components/StoryblokProvider';"
     );
-    // Wrap <html> with StoryblokProvider
     layout = layout.replace(
       '<html lang="en"',
       '<StoryblokProvider>\n\t\t<html lang="en"'
@@ -387,28 +318,17 @@ export default function Teaser({ blok }: { blok: TeaserBlok }) {
     console.log('Warning: Could not update layout.tsx with StoryblokProvider.');
   }
 
-  // Create a sample home page that fetches from Storyblok
-  writeFileSync(join(process.cwd(), 'src', 'app', 'page.tsx'), `import { getStoryblokApi } from '@/lib/storyblok';
-import { StoryblokStory } from '@storyblok/react/rsc';
-
-async function fetchData() {
-  const storyblokApi = getStoryblokApi();
-  return storyblokApi.get('cdn/stories/home', {
-    version: 'draft',
-  });
-}
-
-export default async function Home() {
-  const { data } = await fetchData();
-
-  return (
-    <div>
-      <StoryblokStory story={data.story} />
-    </div>
-  );
-}
-`);
-  console.log('Created sample home page with Storyblok data fetching.');
+  // Add generate-types script to package.json
+  const pkgPath = join(process.cwd(), 'package.json');
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    if (!pkg.scripts) pkg.scripts = {};
+    pkg.scripts['generate-types'] = `storyblok components pull --space ${spaceId} && storyblok types generate --type-suffix Storyblok --space ${spaceId}`;
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    console.log('Added "generate-types" script to package.json.');
+  } catch {
+    console.log('Warning: Could not update package.json with generate-types script.');
+  }
 
   console.log('');
   console.log('=== Storyblok Setup Complete ===');
@@ -417,13 +337,13 @@ export default async function Home() {
   console.log('');
   console.log('  1. Create a Storyblok space at https://app.storyblok.com');
   console.log('');
-  console.log('  2. Copy your Preview token and add it to .env.local:');
-  console.log('     STORYBLOK_PREVIEW_TOKEN=your_preview_token_here');
+  console.log('  2. Add your preview token to .env.local:');
+  console.log('     STORYBLOK_PREVIEW_TOKEN=your_preview_token');
   console.log('');
-  console.log('  3. Make sure you have a "home" story in your Storyblok space');
-  console.log('     with a content type of "page"');
+  console.log('  3. Register your blok components in src/lib/storyblok/bloks.ts');
   console.log('');
-  console.log('  4. Set the Visual Editor URL to https://localhost:3000/');
+  console.log('  4. Generate TypeScript types from your Storyblok space:');
+  console.log('     npm run generate-types');
   console.log('');
   console.log('  5. Start your dev server:');
   console.log('     npm run dev');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@majordigital/create-acorn",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Interactive scaffold for Acorn with Storyblok/Prismic/DatoCMS, TypeScript, and Tailwind.",
   "bin": {
     "create-acorn": "bin/create-acorn.mjs",
@@ -20,6 +20,7 @@
   "files": [
     "bin",
     "template",
+    "storyblok",
     "README.md"
   ],
   "engines": {

package/storyblok/storyblok-api/package.json

@@ -0,0 +1,15 @@
+{
+	"name": "storyblok-api",
+	"version": "1.0.0",
+	"private": true,
+	"scripts": {
+		"generate-types": "storyblok components pull --space <SPACEID> && storyblok types generate --type-suffix Storyblok --space <SPACEID>"
+	},
+	"dependencies": {
+		"@storyblok/js": "^4.2.8",
+		"@storyblok/react": "^5.4.11",
+		"storyblok": "^4.6.13",
+		"storyblok-generate-ts": "^2.2.0",
+		"storyblok-js-client": "^7.1.4",
+	}
+}

package/storyblok/storyblok-api/src/lib/buildCache.ts

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// File to store the CV (content version)
+const BUILD_CV_FILE = path.join(process.cwd(), '.build-cv');
+
+/**
+ * Clears the CV cache file
+ * Should be called at the start of each build
+ */
+export function clearBuildCv(): void {
+	try {
+		if (fs.existsSync(BUILD_CV_FILE)) {
+			fs.unlinkSync(BUILD_CV_FILE);
+		}
+	} catch (_error) {
+		// biome-ignore lint/suspicious/noConsole: needs to warn about build CV clear issues
+		console.warn('Error clearing build CV:', _error);
+	}
+}
+
+/**
+ * Stores the CV (content version) for the build
+ */
+export function storeBuildCv(cv: number): void {
+	try {
+		fs.writeFileSync(BUILD_CV_FILE, cv.toString(), 'utf8');
+	} catch (_error) {
+		// biome-ignore lint/suspicious/noConsole: needs to warn about build CV write issues
+		console.warn('Error writing build CV:', _error);
+	}
+}
+
+/**
+ * Returns the CV (content version) stored during the build
+ * Returns undefined if no CV file exists or if in draft mode
+ */
+export function getBuildCv(): number | undefined {
+	if (fs.existsSync(BUILD_CV_FILE)) {
+		try {
+			const storedCv = fs.readFileSync(BUILD_CV_FILE, 'utf8').trim();
+
+			// If file is empty or being written, treat as if file doesn't exist
+			if (storedCv === '') {
+				return undefined;
+			}
+
+			const cv = parseInt(storedCv, 10);
+
+			if (Number.isNaN(cv)) {
+				// biome-ignore lint/suspicious/noConsole: needs to warn about invalid CV
+				console.warn('Stored CV is not a valid number, ignoring cache');
+				return undefined;
+			}
+
+			return cv;
+		} catch (_error) {
+			// If read fails (e.g., file being written), treat as cache miss
+			return undefined;
+		}
+	}
+
+	return undefined;
+}

package/storyblok/storyblok-api/src/lib/storyblok/bloks.ts

@@ -0,0 +1,24 @@
+import type { SbReactComponentsMap } from '@storyblok/react/rsc';
+
+const atoms = {
+};
+
+const elements = {
+};
+
+const components = {
+};
+
+const sections = {
+};
+
+const layouts = {
+};
+
+export const bloks: SbReactComponentsMap = {
+	...atoms,
+	...elements,
+	...components,
+	...sections,
+	...layouts,
+};

package/storyblok/storyblok-api/src/lib/storyblok/fetch/config.ts

@@ -0,0 +1,47 @@
+/**
+ * Storyblok API config and constants for pagination, filtering, and relations.
+ */
+
+// Pagination limits
+export const MAX_STORIES_PER_PAGE = 100; // Storyblok getStories max
+export const LINKS_PER_PAGE = 1000; // Storyblok getLinks max
+
+// Default cache revalidation
+export const DEFAULT_REVALIDATE = 60 * 60 * 8; // 8 hours
+
+// Fields to exclude from listings for performance
+export const DEFAULT_EXCLUDING_FIELDS = [
+	'content.body',
+	'content.blocks',
+	'content.long_text',
+	'content.richtext',
+	// Add/remove fields based on your schemas
+].join(',');
+
+// Reserved slugs to exclude from sitemaps/routes
+export const reservedSlugs = [
+	'home',
+	'error404',
+	'_not-found',
+	'not-found',
+	'favicon.ico',
+	'robots.txt',
+	'sitemap.xml',
+];
+
+// Dynamic stories/routes to ignore in listings/sitemaps
+export const ignoreDynamicStories: string[] = ['legal'];
+export const ignoreDynamicRoutes: string[] = [
+	'global',
+	'global-settings',
+	'preview',
+];
+export const ignoreListingRoutes: string[][] = [];
+
+// Relations to resolve globally for certain blocks/components
+export const globalResolveRelations = [];
+
+// Per-page settings for various content types
+export const postPerPage = 20;
+export const caseStudiesPerPage = 20;
+export const resourcesPerPage = 20;

package/storyblok/storyblok-api/src/lib/storyblok/fetch/fetchBreadcrumbs.ts

@@ -0,0 +1,125 @@
+import { getStoryblokApi } from '@storyblok/react/rsc';
+import type { ISbStoriesParams } from 'storyblok-js-client';
+
+import { isDraftEnabled } from '@/lib/utils';
+
+import type { ICustomSbStoryData, StoryblokServiceDefaults } from '../types';
+import { DEFAULT_EXCLUDING_FIELDS, DEFAULT_REVALIDATE } from './config';
+
+export interface BreadcrumbItemProps {
+	label: string;
+	href: string;
+	isActive?: boolean;
+}
+
+function labelFromSlug(slug: string): string {
+	const last = slug.split('/').filter(Boolean).pop() ?? slug;
+	return last.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+
+/**
+ * Build breadcrumbs for a Storyblok story (cv ancestor fetch).
+ */
+export const fetchBreadcrumbs = async ({
+	story,
+	draftMode,
+}: {
+	story: ICustomSbStoryData;
+	draftMode?: StoryblokServiceDefaults['draftMode'];
+}): Promise<BreadcrumbItemProps[]> => {
+	// Guard: no story or no slug
+	if (!story || !story.full_slug) return [];
+
+	const isDraft = isDraftEnabled(draftMode);
+
+	// If there is no parent, return the single current crumb
+	if (!story.parent_id) {
+		return [
+			{
+				label:
+					story.content?.heading ??
+					story.name ??
+					labelFromSlug(story.full_slug),
+				href: `/${story.full_slug}`,
+				isActive: true,
+			},
+		];
+	}
+
+	const parts = story.full_slug.split('/').filter(Boolean);
+
+	// Top-level: only itself
+	if (parts.length <= 1) {
+		return [
+			{
+				label:
+					story.content?.heading ??
+					story.name ??
+					labelFromSlug(story.full_slug),
+				href: `/${story.full_slug}`,
+				isActive: true,
+			},
+		];
+	}
+
+	// Parents in order: "a", "a/b", ..., "a/b/.../y"
+	const parentSlugs = parts
+		.slice(0, -1)
+		.map((_, i) => parts.slice(0, i + 1).join('/'));
+
+	try {
+		const storyblokApi = getStoryblokApi();
+		// Build a lean, typed params object for getStories
+		const params: ISbStoriesParams = {
+			version: isDraft ? 'draft' : 'published',
+			...(isDraft ? { cv: Date.now() } : {}),
+			by_slugs: parentSlugs.join(','),
+			per_page: parentSlugs.length,
+			excluding_fields: DEFAULT_EXCLUDING_FIELDS,
+		};
+
+		const storiesRes = await storyblokApi.get('cdn/stories', params, {
+			next: {
+				revalidate: DEFAULT_REVALIDATE,
+			},
+		});
+
+		type SbStoryLite = {
+			full_slug: string;
+			name?: string;
+			content?: { heading?: string };
+		};
+		const items = (storiesRes?.data?.stories ?? []) as SbStoryLite[];
+		const bySlug = new Map(items.map(s => [s.full_slug, s]));
+
+		// Ancestors in the exact same order as parentSlugs, with safe fallbacks
+		const ancestors: BreadcrumbItemProps[] = parentSlugs.map(slug => {
+			const s = bySlug.get(slug);
+			const label = s?.content?.heading ?? s?.name ?? labelFromSlug(slug);
+			return { label, href: `/${slug}`, isActive: false };
+		});
+
+		const current: BreadcrumbItemProps = {
+			label:
+				story.content?.heading ??
+				story.name ??
+				labelFromSlug(story.full_slug),
+			href: `/${story.full_slug}`,
+			isActive: true,
+		};
+
+		return [...ancestors, current];
+	} catch {
+		// Fallback: at least return the current item
+		return [
+			{
+				label:
+					story.content?.heading ??
+					story.name ??
+					labelFromSlug(story.full_slug),
+				href: `/${story.full_slug}`,
+				isActive: true,
+			},
+		];
+	}
+};

package/storyblok/storyblok-api/src/lib/storyblok/fetch/fetchCv.ts

@@ -0,0 +1,45 @@
+import { Storyblok } from 'storyblok-js-client';
+
+import { getBuildCv, storeBuildCv } from '@/lib/buildCache';
+
+// Store the in-flight promise to prevent concurrent API calls
+let cvPromise: Promise<number> | null = null;
+
+export const fetchCv = async (): Promise<number> => {
+	// Try to get cached CV first
+	const cachedCv = getBuildCv();
+
+	if (cachedCv !== undefined) {
+		return cachedCv;
+	}
+
+	// If there's already a fetch in progress, wait for it
+	if (cvPromise !== null) {
+		return cvPromise;
+	}
+
+	// Start a new fetch
+	cvPromise = (async () => {
+		try {
+			// Fetch CV from Storyblok
+			const storyblokClient = new Storyblok({
+				accessToken: process.env.STORYBLOK_PREVIEW_TOKEN,
+				region: 'eu',
+			});
+
+			const cv = await storyblokClient
+				.get('cdn/spaces/me', { version: 'published' })
+				.then(x => x.data.space.version as number);
+
+			// Store CV for subsequent calls
+			storeBuildCv(cv);
+
+			return cv;
+		} finally {
+			// Clear the promise after completion (success or failure)
+			cvPromise = null;
+		}
+	})();
+
+	return cvPromise;
+};

package/storyblok/storyblok-api/src/lib/storyblok/fetch/fetchGlobal.ts

@@ -0,0 +1,48 @@
+import type { ISbStoryParams } from 'storyblok-js-client';
+
+import { getStoryblokApi } from '@/lib/storyblok';
+import { isDraftEnabled } from '@/lib/utils';
+
+import type { StoryblokServiceDefaults } from '../types';
+import { fetchCv } from './fetchCv';
+
+import type { GlobalSettingsStoryblok } from '.storyblok/types/338885/storyblok-components';
+
+/**
+ * Fetch Global Settings (single story) with caching + webhook-friendly tags.
+ * - Draft adds `cv` to bypass CDN.
+ * - Tags allow precise revalidation via `/api/storyblok/revalidate`.
+ */
+export const fetchGlobal = async ({
+	draftMode,
+	revalidate = 900, // 15m; webhook will keep this fresh
+}: {
+	draftMode?: StoryblokServiceDefaults['draftMode'];
+	revalidate?: number;
+}): Promise<GlobalSettingsStoryblok | null> => {
+	const slug = 'global-settings';
+
+	const isDraft = isDraftEnabled(draftMode);
+	const storyblokApi = getStoryblokApi();
+	const cv = isDraft ? undefined : await fetchCv();
+
+	// 2) Narrow, typed Story params (no list fields)
+	const params: ISbStoryParams = {
+		version: isDraft ? 'draft' : 'published',
+		cv,
+		resolve_relations: 'global_settings.footer_legal',
+		resolve_links: 'url',
+	};
+
+	// 3) Direct API call with revalidate
+	const { data } = await storyblokApi.get(`cdn/stories/${slug}`, params, {
+		next: {
+			revalidate,
+		},
+	});
+	const story = data?.story;
+	if (!story) return null;
+
+	// 4) Return content only
+	return story.content as GlobalSettingsStoryblok;
+};