@allejo/decap-extras 0.0.1 → 0.0.3

package/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write # Required for OIDC
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+          package-manager-cache: false
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm test
+      - run: npm publish

package/README.md

@@ -248,8 +248,209 @@ function getPageProps<F extends PageName>(
 }
 ```
 
+## React Integration
+
+Decap CMS is distributed either as [a single `.js` bundle you can load in an HTML file with `<script>` or as an ESM module you can import](https://decapcms.org/docs/install-decap-cms/). In order to integrate type-safety into working with Decap, we want to incorporate Decap CMS as a Next.js page so that we can get all the type-safety from working within it as a framework. There's one small problem with this though...
+
+> You can also use Decap CMS as an npm module. Wherever you import Decap CMS, it automatically runs, taking over the current page.
+
+This means, we can't just import Decap CMS in a Next.js page and call it a day. This is because at build time, Next.js will run the code in the page to generate the static HTML, and if Decap CMS is imported and initialized at that time, it's going to try to take over the page during the build process, which is not what we want. We only want Decap CMS to take over the page when it's running in the browser.
+
+To work around this, we can use [dynamic imports (i.e., `import()`)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) inside a `useEffect` hook to initialize Decap CMS only on the client after the Next.js boilerplate has rendered and allow the CMS instance to take over the page.
+
+```tsx
+useEffect(() => {
+	Promise.all([
+		import('decap-cms-app'),
+
+		// You can import other Decap CMS modules
+		// import('decap-cms-media-library-cloudinary')
+	]).then(([cmsMod /*, cloudinaryMod*/]) => {
+		const cms = cmsMod.default;
+		const cloudinary = cloudinaryMod.default;
+
+		cms.init({ config });
+
+		// ...
+		// cms.registerPreviewStyle(...)
+		// cms.registerPreviewTemplate(...);
+		// cms.registerWidget(...);
+		// cms.registerMediaLibrary(cloudinary);
+	});
+}, []);
+```
+
+> The import() syntax, commonly called dynamic import, is a function-like expression that allows loading an ECMAScript module asynchronously and dynamically into a potentially non-module environment.
+
+Is there a more elegant solution to this problem? I'm not sure! If you can think of one, I would gladly welcome the idea.
+
+But knowing all of this and setting it up gets tedious and boilerplate-y really fast. So, in this package, we export a React component called `DecapInstance` that abstracts away all of this dynamic importing and initialization logic, so you can just use it as a wrapper around your admin page and pass in your config, preview styles, templates, widgets, and Cloudinary flag as props.
+
+### The `<DecapInstance />` Component
+
+We provide a React component called `DecapInstance` that handles the dynamic import and initialization of Decap CMS for you.
+
+```tsx
+import type { PropsByCollectionAndFile } from '@allejo/decap-extras';
+import { getCssFilesFromManifest } from '@allejo/decap-extras/next';
+import { DecapInstance } from '@allejo/decap-extras/react';
+import type { ComponentType } from 'react';
+
+import type { cmsConfig } from '@/cms/config';
+
+// The HomePageProps type and HomePreview component are normally imported from
+// other files, but are included here inline for demonstration purposes.
+type HomePageProps = PropsByCollectionAndFile<
+	typeof cmsConfig,
+	'pages',
+	'home'
+>;
+function HomePreview(props: HomePageProps) {
+	return (
+		<article>
+			<h1>{props.title}</h1>
+			{props.subtitle ? <p>{props.subtitle}</p> : null}
+		</article>
+	);
+}
+
+type AdminProps = {
+	cssFiles: string[];
+};
+
+export async function getStaticProps() {
+	const css = getCssFilesFromManifest(process.env.NODE_ENV ?? 'development', [
+		'/',
+		'/_app',
+	]);
+
+	return {
+		props: {
+			cssFiles: css.flattenedCssFiles,
+		},
+	};
+}
+
+export default function Admin({ cssFiles }: AdminProps) {
+	return (
+		<DecapInstance
+			config={cmsConfig}
+			cssFiles={cssFiles}
+			// Pass explicitly so media-library behavior is visible in admin setup.
+			useCloudinary={true}
+			pages={{
+				home: HomePreview as unknown as ComponentType<never>,
+			}}
+			widgets={{}}
+			onInit={(cms) => {
+				console.log('Decap initialized', cms);
+			}}
+		/>
+	);
+}
+```
+
+### How it Works
+
+`getCssFilesFromManifest` reads Next.js's `.next/build-manifest.json` at build time and returns all CSS files associated with the `/` and `/_app` routes. These are passed as props to the admin page so that we can [register the CSS files into Decap's preview functionality](https://decapcms.org/docs/customization/#registerpreviewstyle).
+
+```ts
+export async function getStaticProps() {
+	const cssFiles = getCssFilesFromManifest(process.env.NODE_ENV, [
+		'/',
+		'/_app',
+	]);
+	return { props: { cssFiles: cssFiles['flattenedCssFiles'] } };
+}
+```
+
+> [!WARNING]
+>
+> This is a bit of a hacky solution to get the CSS files and therefore has some known issues.
+>
+> The CSS for a page might not exist during local development because Next.js only generates the build manifest as the pages are requested. Therefore, if launch `next dev` and immediately open the admin page, the CSS files won't be found for the homepage (i.e., `/`) and won't be registered in the CMS preview, resulting in an unstyled preview. To work around this, you can either visit the homepage first to trigger the generation of the CSS files in the manifest, or run `next build` to generate the manifest with all CSS files before running `next dev`. During local development, this function will check the dev manifest at `.next/dev/build-manifest.json` first, and fallback to the regular manifest at `.next/build-manifest.json` if the dev manifest doesn't exist, so it should work in either case as long as the CSS files have been recorded.
+>
+> If you have a better idea of handling this, please reach out!
+
+#### Initialization sequence inside `useEffect`
+
+```ts
+cms.init({ config });
+```
+
+Bootstraps the CMS with the config from `src/cms/config.ts`.
+
+```ts
+cssFiles.forEach((css) => cms.registerPreviewStyle(css));
+```
+
+Registers every collected CSS file with the CMS preview panel so the editor renders with production styles.
+
+> [!WARNING]
+>
+> **FIXME**: There HAS to be a better way of handling this so that we only load the relevant stylesheets for specific previews. I'm not sure how to solve this yet, but I'll come back to it.
+
+```ts
+cms.registerPreviewTemplate(pageId, ({ entry }) => {
+  return <Component {...entry.get('data').toJSON()} />;
+});
+```
+
+Maps each CMS page entry (`home`, etc.) to its real Next.js page component, passing the editor's live data as props. Editors see the actual production component rendering their changes in real time.
+
+```ts
+cms.registerMediaLibrary(cloudinary);
+```
+
+Registers the Cloudinary media picker.
+
+> [!WARNING]
+>
+> Being able to _disable_ Cloudinary is a work-in-progress. I've always needed it for the projects I'm building so it's enabled by default. I'll get to respecting the "disable" environment variable... eventually.
+
+## Server utilities
+
+A server-side utility for getting CSS from Next.js build manifests. This is useful for registering CSS stylesheets into Decap's CMS preview system.
+
+```ts
+import { getCssFilesFromManifest } from '@allejo/decap-extras/next';
+```
+
+Use `getCssFilesFromManifest` in `getStaticProps` to collect the CSS paths needed by your page and pass them as props:
+
+```ts
+export async function getStaticProps() {
+	const cssFiles = getCssFilesFromManifest(process.env.NODE_ENV, [
+		'/',
+		'/_app',
+	]);
+
+	return {
+		props: {
+			cssFiles: cssFiles['flattenedCssFiles'],
+		},
+	};
+}
+```
+
+Then register each path as a preview stylesheet in your Decap CMS admin component:
+
+```ts
+export default function Admin({ cssFiles }: Props) {
+	// ...
+
+	cssFiles.forEach((css) => {
+		cms.registerPreviewStyle(css);
+	});
+}
+```
+
+> **Note:** This utility reads `.next/build-manifest.json` (or `.next/dev/build-manifest.json` in development) and is intended for Next.js projects only.
+
 ---
 
+## API reference
+
 ### Widget functions
 
 | Function                                     | Decap widget                                                   | TypeScript type           |
@@ -283,6 +484,19 @@ function getPageProps<F extends PageName>(
 | `OptionalWidget<T>`                       | Brands a `CmsField` as optional (added by `optional()`).                             |
 | `WidgetOpts<T>`                           | The options type for a given widget field type, with `widget` and `fields` stripped. |
 
+### Server utilities
+
+| Function                              | Description                                                                                                                                                              |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `getCssFilesFromManifest(env, pages)` | Reads the Next.js build manifest and returns CSS paths for the given page routes, grouped by page (`allCssFiles`) and as a deduplicated flat list (`flattenedCssFiles`). |
+
+### React utilities
+
+| Type/Function        | Description                                                                                                                                              |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DecapInstance`      | React component that initializes Decap CMS, registers preview CSS/templates/widgets, optionally enables Cloudinary, and returns `null` after setup.      |
+| `DecapInstanceProps` | Props contract for `DecapInstance`, including config, preview CSS paths, page template registry, widget registry, and optional `onInit`/`useCloudinary`. |
+
 ## License
 
 MIT

package/dist/next/index.d.mts

@@ -0,0 +1,27 @@
+//#region src/next/index.d.ts
+/**
+ * Reads the Next.js build manifest and extracts CSS file paths for the given
+ * pages, resolving the manifest location based on the current environment.
+ *
+ * In development, reads from `.next/dev/build-manifest.json`; in all other
+ * environments, reads from `.next/build-manifest.json`.
+ *
+ * CSS paths are rewritten from the `static/` prefix used internally by Next.js
+ * to the `/_next/static/` public URL path.
+ *
+ * @param env - The current environment (e.g. `"development"` or `"production"`).
+ * @param pages - List of Next.js page routes to extract CSS files for
+ *   (e.g. `["/", "/_app"]`).
+ *
+ * @returns An object with two properties:
+ *   - `allCssFiles` — a map of page route to its CSS file paths.
+ *   - `flattenedCssFiles` — a deduplicated flat list of all CSS file paths
+ *     across every requested page.
+ */
+declare function getCssFilesFromManifest(env: string, pages: string[]): {
+  flattenedCssFiles: string[];
+  allCssFiles: Record<string, string[]>;
+};
+//#endregion
+export { getCssFilesFromManifest };
+//# sourceMappingURL=index.d.mts.map

package/dist/next/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/next/index.ts"],"mappings":";;AAsBA;;;;;;;;;;;;;;;;;;iBAAgB,uBAAA,CAAwB,GAAA,UAAa,KAAA;;eAAd,MAAA;AAAA"}

package/dist/next/index.mjs

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import path from "node:path";
+
+//#region src/next/index.ts
+/**
+* Reads the Next.js build manifest and extracts CSS file paths for the given
+* pages, resolving the manifest location based on the current environment.
+*
+* In development, reads from `.next/dev/build-manifest.json`; in all other
+* environments, reads from `.next/build-manifest.json`.
+*
+* CSS paths are rewritten from the `static/` prefix used internally by Next.js
+* to the `/_next/static/` public URL path.
+*
+* @param env - The current environment (e.g. `"development"` or `"production"`).
+* @param pages - List of Next.js page routes to extract CSS files for
+*   (e.g. `["/", "/_app"]`).
+*
+* @returns An object with two properties:
+*   - `allCssFiles` — a map of page route to its CSS file paths.
+*   - `flattenedCssFiles` — a deduplicated flat list of all CSS file paths
+*     across every requested page.
+*/
+function getCssFilesFromManifest(env, pages) {
+	const devManifestPath = path.join(process.cwd(), ".next", "dev", "build-manifest.json");
+	const manifestPath = path.join(process.cwd(), ".next", "build-manifest.json");
+	const devBuildManifest = fs.existsSync(devManifestPath) ? JSON.parse(fs.readFileSync(devManifestPath, "utf8")) : null;
+	const buildManifest = fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, "utf8")) : null;
+	const allCssFiles = {};
+	const flattenedCssFilesSet = /* @__PURE__ */ new Set();
+	pages.forEach((page) => {
+		const assets = env === "production" ? buildManifest?.pages[page] : devBuildManifest?.pages[page] ?? buildManifest?.pages[page];
+		if (!assets) throw new Error(`No manifest found for ${page}. Ensure "next build" has been run at least once.`);
+		assets.filter((file) => file.endsWith(".css")).forEach((file) => {
+			if (!allCssFiles[page]) allCssFiles[page] = [];
+			const fullPath = file.replace("static/", "/_next/static/");
+			allCssFiles[page].push(fullPath);
+			flattenedCssFilesSet.add(fullPath);
+		});
+	});
+	return {
+		flattenedCssFiles: [...flattenedCssFilesSet],
+		allCssFiles
+	};
+}
+
+//#endregion
+export { getCssFilesFromManifest };
+//# sourceMappingURL=index.mjs.map

package/dist/next/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/next/index.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\n\n/**\n * Reads the Next.js build manifest and extracts CSS file paths for the given\n * pages, resolving the manifest location based on the current environment.\n *\n * In development, reads from `.next/dev/build-manifest.json`; in all other\n * environments, reads from `.next/build-manifest.json`.\n *\n * CSS paths are rewritten from the `static/` prefix used internally by Next.js\n * to the `/_next/static/` public URL path.\n *\n * @param env - The current environment (e.g. `\"development\"` or `\"production\"`).\n * @param pages - List of Next.js page routes to extract CSS files for\n *   (e.g. `[\"/\", \"/_app\"]`).\n *\n * @returns An object with two properties:\n *   - `allCssFiles` — a map of page route to its CSS file paths.\n *   - `flattenedCssFiles` — a deduplicated flat list of all CSS file paths\n *     across every requested page.\n */\nexport function getCssFilesFromManifest(env: string, pages: string[]) {\n\tconst devManifestPath = path.join(\n\t\tprocess.cwd(),\n\t\t'.next',\n\t\t'dev',\n\t\t'build-manifest.json',\n\t);\n\tconst manifestPath = path.join(process.cwd(), '.next', 'build-manifest.json');\n\n\tconst devBuildManifest = fs.existsSync(devManifestPath)\n\t\t? JSON.parse(fs.readFileSync(devManifestPath, 'utf8'))\n\t\t: null;\n\tconst buildManifest = fs.existsSync(manifestPath)\n\t\t? JSON.parse(fs.readFileSync(manifestPath, 'utf8'))\n\t\t: null;\n\n\tconst allCssFiles: Record<string, string[]> = {};\n\tconst flattenedCssFilesSet = new Set<string>();\n\n\tpages.forEach((page) => {\n\t\tconst assets: string[] | undefined =\n\t\t\tenv === 'production'\n\t\t\t\t? buildManifest?.pages[page]\n\t\t\t\t: (devBuildManifest?.pages[page] ?? buildManifest?.pages[page]);\n\n\t\tif (!assets) {\n\t\t\tthrow new Error(\n\t\t\t\t`No manifest found for ${page}. Ensure \"next build\" has been run at least once.`,\n\t\t\t);\n\t\t}\n\n\t\tassets\n\t\t\t.filter((file: string) => file.endsWith('.css'))\n\t\t\t.forEach((file: string) => {\n\t\t\t\tif (!allCssFiles[page]) {\n\t\t\t\t\tallCssFiles[page] = [];\n\t\t\t\t}\n\n\t\t\t\tconst fullPath = file.replace('static/', '/_next/static/');\n\n\t\t\t\tallCssFiles[page].push(fullPath);\n\t\t\t\tflattenedCssFilesSet.add(fullPath);\n\t\t\t});\n\t});\n\n\treturn {\n\t\tflattenedCssFiles: [...flattenedCssFilesSet],\n\t\tallCssFiles,\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,wBAAwB,KAAa,OAAiB;CACrE,MAAM,kBAAkB,KAAK,KAC5B,QAAQ,IAAI,GACZ,SACA,OACA,qBACD;CACA,MAAM,eAAe,KAAK,KAAK,QAAQ,IAAI,GAAG,SAAS,qBAAqB;CAE5E,MAAM,mBAAmB,GAAG,WAAW,eAAe,IACnD,KAAK,MAAM,GAAG,aAAa,iBAAiB,MAAM,CAAC,IACnD;CACH,MAAM,gBAAgB,GAAG,WAAW,YAAY,IAC7C,KAAK,MAAM,GAAG,aAAa,cAAc,MAAM,CAAC,IAChD;CAEH,MAAM,cAAwC,CAAC;CAC/C,MAAM,uCAAuB,IAAI,IAAY;CAE7C,MAAM,SAAS,SAAS;EACvB,MAAM,SACL,QAAQ,eACL,eAAe,MAAM,QACpB,kBAAkB,MAAM,SAAS,eAAe,MAAM;EAE3D,IAAI,CAAC,QACJ,MAAM,IAAI,MACT,yBAAyB,KAAK,kDAC/B;EAGD,OACE,QAAQ,SAAiB,KAAK,SAAS,MAAM,CAAC,EAC9C,SAAS,SAAiB;GAC1B,IAAI,CAAC,YAAY,OAChB,YAAY,QAAQ,CAAC;GAGtB,MAAM,WAAW,KAAK,QAAQ,WAAW,gBAAgB;GAEzD,YAAY,MAAM,KAAK,QAAQ;GAC/B,qBAAqB,IAAI,QAAQ;EAClC,CAAC;CACH,CAAC;CAED,OAAO;EACN,mBAAmB,CAAC,GAAG,oBAAoB;EAC3C;CACD;AACD"}

package/dist/react/index.d.mts

@@ -0,0 +1,107 @@
+import { ComponentClass, ComponentType } from "react";
+import { CMS, CmsConfig, CmsWidgetControlProps, CmsWidgetPreviewProps } from "decap-cms-core";
+
+//#region src/react/DecapInstance.d.ts
+/**
+ * Props for {@link DecapInstance}.
+ *
+ * This object describes everything needed to initialize the Decap CMS runtime
+ * in a React/Next.js admin page.
+ */
+interface DecapInstanceProps {
+  /**
+   * Decap CMS configuration object passed to `cms.init({ config })`.
+   *
+   * @example
+   * const config = {
+   * 	backend: { name: 'git-gateway' },
+   * 	collections: [...],
+   * } as const;
+   */
+  config: CmsConfig;
+  /**
+   * Stylesheets that should be available inside preview panes.
+   *
+   * This is commonly generated in Next.js via
+   * `getCssFilesFromManifest(process.env.NODE_ENV, ['/', '/_app'])` and passed
+   * through page props.
+   */
+  cssFiles: string[];
+  /**
+   * Map of preview template IDs to React components.
+   *
+   * Each component receives the serialized entry data as props
+   * (`entry.get('data').toJSON()`). In practice, this lets you pair inferred
+   * content types from `PropsByCollectionAndFile` with your preview templates.
+   */
+  pages: Record<string, ComponentType<never>>;
+  /**
+   * Optional callback invoked after Decap has been initialized and all
+   * templates/widgets have been registered.
+   *
+   * Use this hook for custom registration that depends on the CMS instance.
+   *
+   * @example
+   * onInit: (cms) => {
+   * 	cms.registerEditorComponent({
+   * 		id: 'callout',
+   * 		label: 'Callout',
+   * 	});
+   * }
+   */
+  onInit?: (cms: CMS) => void;
+  /**
+   * Enables Cloudinary media library registration when set to `true`.
+   *
+   * Defaults to `false`. Pass this explicitly so the admin setup remains
+   * obvious to future maintainers.
+   */
+  useCloudinary?: boolean;
+  /**
+   * Registry of custom widgets to register with Decap.
+   *
+   * @example
+   * widgets: {
+   * 	color: {
+   * 		control: ColorControl,
+   * 		preview: ColorPreview,
+   * 	},
+   * }
+   */
+  widgets: Record<string, {
+    /**
+     * Widget editor component used in the Decap entry form.
+     */
+    control: ComponentClass<CmsWidgetControlProps<unknown>>;
+    /**
+     * Widget preview component used in Decap preview rendering.
+     */
+    preview: ComponentType<CmsWidgetPreviewProps<unknown>>;
+  }>;
+}
+/**
+ * Initializes Decap CMS from a React component, then returns `null`.
+ *
+ * This component performs all setup in a `useEffect` call: it boots Decap,
+ * registers preview CSS, wires preview templates, registers custom widgets,
+ * optionally enables Cloudinary, and finally calls `onInit`.
+ *
+ * @example
+ * import type { PropsByCollectionAndFile } from '@allejo/decap-extras';
+ * import { DecapInstance } from '@allejo/decap-extras/react';
+ *
+ * import type { cmsConfig } from '@/cms/config';
+ *
+ * type HomePageProps = PropsByCollectionAndFile<typeof cmsConfig, 'pages', 'home'>;
+ */
+declare const DecapInstance: ({
+  config,
+  cssFiles,
+  onInit,
+  pages,
+  useCloudinary,
+  widgets
+}: DecapInstanceProps) => null;
+//#endregion
+export { DecapInstance, type DecapInstanceProps };
+//# sourceMappingURL=index.d.mts.map

package/dist/react/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/react/DecapInstance.tsx"],"mappings":";;;;;;AAcA;;;;UAAiB,kBAAA;EA0BT;;;;;;;;;EAhBP,MAAA,EAAQ,SAAA;EAAA;;;;;;;EAQR,QAAA;EA8BA;;;;;;;EAtBA,KAAA,EAAO,MAAA,SAAe,aAAA;EA4CG;;AAAqB;AAoB/C;;;;;;;;;;;EAjDC,MAAA,IAAU,GAAA,EAAK,GAAA;EAiDc;;;;;;EA1C7B,aAAA;EA0C6B;;;;;;;AAOT;;;;EArCpB,OAAA,EAAS,MAAA;;;;IAMP,OAAA,EAAS,cAAA,CAAe,qBAAA;;;;IAIxB,OAAA,EAAS,aAAA,CAAc,qBAAA;EAAA;AAAA;;;;;;;;;;;;;;;;cAoBb,aAAA;EAAiB,MAAA;EAAA,QAAA;EAAA,MAAA;EAAA,KAAA;EAAA,aAAA;EAAA;AAAA,GAO3B,kBAAA"}

package/dist/react/index.mjs

@@ -0,0 +1,46 @@
+import { useEffect } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/react/DecapInstance.tsx
+/**
+* Initializes Decap CMS from a React component, then returns `null`.
+*
+* This component performs all setup in a `useEffect` call: it boots Decap,
+* registers preview CSS, wires preview templates, registers custom widgets,
+* optionally enables Cloudinary, and finally calls `onInit`.
+*
+* @example
+* import type { PropsByCollectionAndFile } from '@allejo/decap-extras';
+* import { DecapInstance } from '@allejo/decap-extras/react';
+*
+* import type { cmsConfig } from '@/cms/config';
+*
+* type HomePageProps = PropsByCollectionAndFile<typeof cmsConfig, 'pages', 'home'>;
+*/
+const DecapInstance = ({ config, cssFiles, onInit, pages, useCloudinary = false, widgets }) => {
+	useEffect(() => {
+		Promise.all([import("decap-cms-app"), useCloudinary ? import("decap-cms-media-library-cloudinary") : Promise.resolve(null)]).then(([cmsMod, cloudinaryMod]) => {
+			const cms = cmsMod.default;
+			const cloudinary = cloudinaryMod.default;
+			cms.init({ config });
+			cssFiles.forEach((css) => {
+				cms.registerPreviewStyle(css);
+			});
+			Object.entries(pages).forEach(([pageId, PageComponent]) => {
+				cms.registerPreviewTemplate(pageId, ({ entry }) => {
+					return /* @__PURE__ */ jsx(PageComponent, { ...entry.get("data").toJSON() });
+				});
+			});
+			Object.entries(widgets).forEach(([widgetId, { control, preview }]) => {
+				cms.registerWidget(widgetId, control, preview);
+			});
+			if (cloudinaryMod) cms.registerMediaLibrary(cloudinary);
+			onInit?.(cms);
+		});
+	}, [cssFiles]);
+	return null;
+};
+
+//#endregion
+export { DecapInstance };
+//# sourceMappingURL=index.mjs.map

package/dist/react/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["Component"],"sources":["../../src/react/DecapInstance.tsx"],"sourcesContent":["import type {\n\tCMS,\n\tCmsConfig,\n\tCmsWidgetControlProps,\n\tCmsWidgetPreviewProps,\n} from 'decap-cms-core';\nimport { ComponentClass, ComponentType, useEffect } from 'react';\n\n/**\n * Props for {@link DecapInstance}.\n *\n * This object describes everything needed to initialize the Decap CMS runtime\n * in a React/Next.js admin page.\n */\nexport interface DecapInstanceProps {\n\t/**\n\t * Decap CMS configuration object passed to `cms.init({ config })`.\n\t *\n\t * @example\n\t * const config = {\n\t * \tbackend: { name: 'git-gateway' },\n\t * \tcollections: [...],\n\t * } as const;\n\t */\n\tconfig: CmsConfig;\n\t/**\n\t * Stylesheets that should be available inside preview panes.\n\t *\n\t * This is commonly generated in Next.js via\n\t * `getCssFilesFromManifest(process.env.NODE_ENV, ['/', '/_app'])` and passed\n\t * through page props.\n\t */\n\tcssFiles: string[];\n\t/**\n\t * Map of preview template IDs to React components.\n\t *\n\t * Each component receives the serialized entry data as props\n\t * (`entry.get('data').toJSON()`). In practice, this lets you pair inferred\n\t * content types from `PropsByCollectionAndFile` with your preview templates.\n\t */\n\tpages: Record<string, ComponentType<never>>;\n\t/**\n\t * Optional callback invoked after Decap has been initialized and all\n\t * templates/widgets have been registered.\n\t *\n\t * Use this hook for custom registration that depends on the CMS instance.\n\t *\n\t * @example\n\t * onInit: (cms) => {\n\t * \tcms.registerEditorComponent({\n\t * \t\tid: 'callout',\n\t * \t\tlabel: 'Callout',\n\t * \t});\n\t * }\n\t */\n\tonInit?: (cms: CMS) => void;\n\t/**\n\t * Enables Cloudinary media library registration when set to `true`.\n\t *\n\t * Defaults to `false`. Pass this explicitly so the admin setup remains\n\t * obvious to future maintainers.\n\t */\n\tuseCloudinary?: boolean;\n\t/**\n\t * Registry of custom widgets to register with Decap.\n\t *\n\t * @example\n\t * widgets: {\n\t * \tcolor: {\n\t * \t\tcontrol: ColorControl,\n\t * \t\tpreview: ColorPreview,\n\t * \t},\n\t * }\n\t */\n\twidgets: Record<\n\t\tstring,\n\t\t{\n\t\t\t/**\n\t\t\t * Widget editor component used in the Decap entry form.\n\t\t\t */\n\t\t\tcontrol: ComponentClass<CmsWidgetControlProps<unknown>>;\n\t\t\t/**\n\t\t\t * Widget preview component used in Decap preview rendering.\n\t\t\t */\n\t\t\tpreview: ComponentType<CmsWidgetPreviewProps<unknown>>;\n\t\t}\n\t>;\n}\n\n/**\n * Initializes Decap CMS from a React component, then returns `null`.\n *\n * This component performs all setup in a `useEffect` call: it boots Decap,\n * registers preview CSS, wires preview templates, registers custom widgets,\n * optionally enables Cloudinary, and finally calls `onInit`.\n *\n * @example\n * import type { PropsByCollectionAndFile } from '@allejo/decap-extras';\n * import { DecapInstance } from '@allejo/decap-extras/react';\n *\n * import type { cmsConfig } from '@/cms/config';\n *\n * type HomePageProps = PropsByCollectionAndFile<typeof cmsConfig, 'pages', 'home'>;\n */\nexport const DecapInstance = ({\n\tconfig,\n\tcssFiles,\n\tonInit,\n\tpages,\n\tuseCloudinary = false,\n\twidgets,\n}: DecapInstanceProps) => {\n\tuseEffect(() => {\n\t\tPromise.all([\n\t\t\timport('decap-cms-app'),\n\t\t\tuseCloudinary\n\t\t\t\t? // @ts-expect-error package has no types\n\t\t\t\t\timport('decap-cms-media-library-cloudinary')\n\t\t\t\t: Promise.resolve(null),\n\t\t]).then(([cmsMod, cloudinaryMod]) => {\n\t\t\tconst cms = cmsMod.default;\n\t\t\tconst cloudinary = cloudinaryMod.default;\n\n\t\t\tcms.init({ config });\n\n\t\t\tcssFiles.forEach((css) => {\n\t\t\t\tcms.registerPreviewStyle(css);\n\t\t\t});\n\n\t\t\tObject.entries(pages).forEach(([pageId, PageComponent]) => {\n\t\t\t\tcms.registerPreviewTemplate(pageId, ({ entry }) => {\n\t\t\t\t\tconst Component = PageComponent as ComponentType<\n\t\t\t\t\t\tRecord<string, unknown>\n\t\t\t\t\t>;\n\n\t\t\t\t\treturn <Component {...entry.get('data').toJSON()} />;\n\t\t\t\t});\n\t\t\t});\n\n\t\t\tObject.entries(widgets).forEach(([widgetId, { control, preview }]) => {\n\t\t\t\tcms.registerWidget(widgetId, control, preview);\n\t\t\t});\n\n\t\t\tif (cloudinaryMod) {\n\t\t\t\tcms.registerMediaLibrary(cloudinary);\n\t\t\t}\n\n\t\t\tonInit?.(cms);\n\t\t});\n\t}, [cssFiles]);\n\n\treturn null;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAwGA,MAAa,iBAAiB,EAC7B,QACA,UACA,QACA,OACA,gBAAgB,OAChB,cACyB;CACzB,gBAAgB;EACf,QAAQ,IAAI,CACX,OAAO,kBACP,gBAEE,OAAO,wCACN,QAAQ,QAAQ,IAAI,CACxB,CAAC,EAAE,MAAM,CAAC,QAAQ,mBAAmB;GACpC,MAAM,MAAM,OAAO;GACnB,MAAM,aAAa,cAAc;GAEjC,IAAI,KAAK,EAAE,OAAO,CAAC;GAEnB,SAAS,SAAS,QAAQ;IACzB,IAAI,qBAAqB,GAAG;GAC7B,CAAC;GAED,OAAO,QAAQ,KAAK,EAAE,SAAS,CAAC,QAAQ,mBAAmB;IAC1D,IAAI,wBAAwB,SAAS,EAAE,YAAY;KAKlD,OAAO,oBAACA,eAAD,EAAW,GAAI,MAAM,IAAI,MAAM,EAAE,OAAO,EAAI;IACpD,CAAC;GACF,CAAC;GAED,OAAO,QAAQ,OAAO,EAAE,SAAS,CAAC,UAAU,EAAE,SAAS,eAAe;IACrE,IAAI,eAAe,UAAU,SAAS,OAAO;GAC9C,CAAC;GAED,IAAI,eACH,IAAI,qBAAqB,UAAU;GAGpC,SAAS,GAAG;EACb,CAAC;CACF,GAAG,CAAC,QAAQ,CAAC;CAEb,OAAO;AACR"}

package/package.json

@@ -1,19 +1,31 @@
 {
 	"name": "@allejo/decap-extras",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"description": "A TypeScript utility library for Decap CMS with utility types to derive types from Decap CMS configuration files.",
 	"keywords": [
 		"decapcms"
 	],
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/allejo/decap-extras"
+		"url": "git+https://github.com/allejo/decap-extras.git"
 	},
 	"license": "MIT",
 	"author": "Vladimir \"allejo\" Jimenez",
 	"type": "module",
-	"main": "./dist/index.mjs",
-	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs"
+		},
+		"./react": {
+			"types": "./dist/react/index.d.mts",
+			"import": "./dist/react/index.mjs"
+		},
+		"./next": {
+			"types": "./dist/next/index.d.mts",
+			"import": "./dist/next/index.mjs"
+		}
+	},
 	"scripts": {
 		"build": "tsdown",
 		"format": "prettier --write .",
@@ -31,15 +43,19 @@
 		"@types/eslint": "^8.44.7",
 		"@types/node": "^24.12.4",
 		"decap-cms-app": "^3.12.2",
+		"decap-cms-media-library-cloudinary": "^3.1.0",
 		"eslint": "^9.21.0",
 		"husky": "^9.0.10",
 		"lint-staged": "^15.4.3",
 		"prettier": "^3.1.1",
+		"react": "^19.2.6",
 		"tsdown": "^0.22.0",
 		"typescript": "^5.9.3",
 		"vitest": "^3.2.4"
 	},
 	"peerDependencies": {
-		"decap-cms-core": "^3.12.2"
+		"decap-cms-core": "^3.12.2",
+		"decap-cms-media-library-cloudinary": "^3.1.0",
+		"react": "16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
 	}
 }