From f5ec4fd90c460477e7e416151226aa3f4863a9b1 Mon Sep 17 00:00:00 2001 From: hiteshshetty-dev Date: Mon, 30 Mar 2026 18:05:53 +0530 Subject: [PATCH 1/8] docs(readme): expand package README for preview, Timeline, Visual Editor, Studio (VB-665) - Add npm and license badges, async init quick start, config index links - Document Live Preview, Timeline, Visual Builder, and Composable Studio contexts - Link canonical Contentstack docs, Academy (including Understanding Timeline), and Studio Made-with: Cursor --- README.md | 125 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 94 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index c826f875..cbdaa212 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,123 @@ -# Contentstack Live Preview Utils SDK +# @contentstack/live-preview-utils -Contentstack is a headless CMS with an API-first approach. It is a CMS that developers can use to build powerful cross-platform applications in their favorite languages. Build your application frontend, and Contentstack will take care of the rest. +[![npm](https://img.shields.io/npm/v/@contentstack/live-preview-utils.svg)](https://www.npmjs.com/package/@contentstack/live-preview-utils) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -Contentstack provides the Live Preview Utils SDK to establish a communication channel between the various Contentstack SDKs and your website, transmitting live changes to the preview pane. [Read More](https://www.contentstack.com/docs/content-managers/live-preview/). +The **Live Preview Utils** package runs in your website and opens a communication channel between the page (often inside a Contentstack preview iframe) and the platform. It powers live content updates, edit controls, and Visual Builder UI in the preview surface via messaging—not a replacement for the Contentstack delivery SDKs, but the client bridge for preview and builder experiences. -# Installation +See how [Live Preview](https://www.contentstack.com/docs/content-managers/author-content/about-live-preview), [Timeline](https://www.contentstack.com/docs/content-managers/timeline/preview-content-across-a-timeline), and [Visual Editor](https://www.contentstack.com/docs/content-managers/visual-editor/about-visual-editor) work in Contentstack for editors and content managers. -To install the package via npm, use the following command: +## Where this SDK runs + +- **Live Preview** — Preview entries in the stack while your site loads inside the preview panel. +- **Timeline** — Time-based preview (how the site looks on future dates). Your integration pattern is the same as Live Preview from the app’s perspective; the parent context is still a preview iframe. In code, `config.windowType` can reflect a preview context that includes Timeline ([see `config` / `windowType`](docs/live-preview-configs.md#config)). +- **Visual Builder** — WYSIWYG editing with the site in an iframe. Use `mode: "builder"` so “Start Editing” targets Visual Builder; the SDK still works when the same site is opened in Live Preview ([`mode`](docs/live-preview-configs.md#mode)). +- **Composable Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is the visual composition experience for building experiences from components and content. Use this package when your front end needs the same live preview and stack-driven editing hooks as in Live Preview; follow Studio and Live Preview setup docs together for your stack. + +**Integrators:** In hosted preview, the platform loads your site in an iframe; this SDK talks to the parent window. When you open the site outside Contentstack (`windowType: independent`), behavior follows the [config](docs/live-preview-configs.md#config) rules in the reference doc. + +## Requirements + +- **Browser:** Initialize only on the client (`window` must exist). Server-only bundles should not call `init` during SSR. +- **SSR vs CSR:** Defaults assume SSR-friendly behavior. For **client-side rendering**, pass [`stackSdk`](docs/live-preview-configs.md#stacksdk) and set [`ssr: false`](docs/live-preview-configs.md#ssr) as described in the config reference. + +## Installation ```bash npm install @contentstack/live-preview-utils ``` -Alternatively, if you want to include the package directly in your website HTML code, use the following command: +### Load from a CDN (advanced) + +Pin the version to match your app (update `4.3.0` when you upgrade): ```html - ``` -> [!NOTE] -> This step involves incorporating the package into your HTML code and initializing it, eliminating the need for re-initialization in the subsequent step. - -# Initializing the SDK +> [!TIP] +> If you bootstrap with the snippet above, skip a second `init` from your app bundle on the same page. -### Live Preview Utils +## Quick start -Since the Live Preview Utils SDK is responsible for communication, you need to only initialize it. -Use the following command to initialize the SDK: +[`init`](docs/live-preview-configs.md#initconfig-iconfig) returns a `Promise` that resolves to `{ livePreview, visualBuilder }`. Calling `init` again returns the existing instance and logs a warning. ```javascript import ContentstackLivePreview from "@contentstack/live-preview-utils"; -ContentstackLivePreview.init({ - stackDetails: { - apiKey: "your-stack-api-key", - }, +const { livePreview, visualBuilder } = await ContentstackLivePreview.init({ + stackDetails: { + apiKey: "your-stack-api-key", + }, }); ``` +## Configuration + +Full tables and examples: **[docs/live-preview-configs.md](docs/live-preview-configs.md)**. -# License +**`init` options** -MIT License +- [`enable`](docs/live-preview-configs.md#enable) +- [`ssr`](docs/live-preview-configs.md#ssr) +- [`mode`](docs/live-preview-configs.md#mode) (`preview` vs `builder`) +- [`editButton`](docs/live-preview-configs.md#editbutton) +- [`editInVisualBuilderButton`](docs/live-preview-configs.md#editinvisualbuilderbutton) (Start Editing outside Visual Builder) +- [`cleanCslpOnProduction`](docs/live-preview-configs.md#cleancslponproduction) +- [`stackDetails`](docs/live-preview-configs.md#stackdetails) ([`apiKey`](docs/live-preview-configs.md#apikey), [`environment`](docs/live-preview-configs.md#environment)) +- [`clientUrlParams`](docs/live-preview-configs.md#clienturlparams) — [NA](docs/live-preview-configs.md#na-config) / [EU](docs/live-preview-configs.md#eu-config) +- [`stackSdk`](docs/live-preview-configs.md#stacksdk) -Copyright © 2021-2026 [Contentstack](https://www.contentstack.com/). All Rights Reserved +**Methods and properties** -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: +- [`onLiveEdit`](docs/live-preview-configs.md#onliveeditcallback---void) +- [`onEntryChange`](docs/live-preview-configs.md#onentrychangecallback---void) +- [`hash`](docs/live-preview-configs.md#hash) +- [`config`](docs/live-preview-configs.md#config) (includes `windowType`: Live Preview / Timeline preview, Visual Builder, or independent) + +The [configs table of contents](docs/live-preview-configs.md#contentstack-live-preview-utils-sdk-configs) also lists `setConfigFromParams` and `getGatsbyDataFormat` for deeper workflows. + +## Documentation and learning + +**Developers** + +- [Set up Live Preview for your website](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-your-website) +- [How Live Preview works](https://www.contentstack.com/docs/developers/set-up-live-preview/how-live-preview-works) +- [Preview API](https://www.contentstack.com/docs/developers/set-up-timeline/preview-api) +- [Set up Timeline for your website](https://www.contentstack.com/docs/developers/set-up-timeline/set-up-timeline-for-your-website) + +**Content managers** + +- [About Live Preview](https://www.contentstack.com/docs/content-managers/author-content/about-live-preview) +- [Preview content across a Timeline](https://www.contentstack.com/docs/content-managers/timeline/preview-content-across-a-timeline) +- [About Visual Editor](https://www.contentstack.com/docs/content-managers/visual-editor/about-visual-editor) + +**Studio** + +- [Studio](https://www.contentstack.com/docs/studio) +- [Get started with Studio](https://www.contentstack.com/docs/studio/get-started-with-studio) + +**Academy** + +- [Implementing Live Preview (course)](https://www.contentstack.com/academy/courses/implementing-live-preview) +- [Contentstack Live Preview under the hood](https://www.contentstack.com/academy/content/contentstack-live-preview-under-the-hood) +- [Understanding Timeline](https://www.contentstack.com/academy/content/understanding-timeline) +- [Understanding Visual Builder](https://www.contentstack.com/academy/content/understanding-visual-builder) + +## Advanced: stripping the SDK at build time + +> [!NOTE] +> Set `PURGE_PREVIEW_SDK` or `REACT_APP_PURGE_PREVIEW_SDK` to `"true"` at build time to swap the default export for a light stub so preview code is not bundled for production. -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. +## Resources -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +- **Source:** [github.com/contentstack/live-preview-sdk](https://github.com/contentstack/live-preview-sdk) +- **Typed API (local):** `npm run docs` From de2e43e028e264f460b60b9d8b710f4524e138fa Mon Sep 17 00:00:00 2001 From: hiteshshetty-dev Date: Mon, 30 Mar 2026 18:30:32 +0530 Subject: [PATCH 2/8] docs(readme): update terminology from Visual Builder to Visual Editor --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index cbdaa212..4b3c5227 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![npm](https://img.shields.io/npm/v/@contentstack/live-preview-utils.svg)](https://www.npmjs.com/package/@contentstack/live-preview-utils) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -The **Live Preview Utils** package runs in your website and opens a communication channel between the page (often inside a Contentstack preview iframe) and the platform. It powers live content updates, edit controls, and Visual Builder UI in the preview surface via messaging—not a replacement for the Contentstack delivery SDKs, but the client bridge for preview and builder experiences. +The **Live Preview Utils** package runs in your website and opens a communication channel between the page (often inside a Contentstack preview iframe) and the platform. It powers live content updates, edit controls, and Visual Editor UI in the preview surface via messaging—not a replacement for the Contentstack delivery SDKs, but the client bridge for preview and Visual Editor experiences. See how [Live Preview](https://www.contentstack.com/docs/content-managers/author-content/about-live-preview), [Timeline](https://www.contentstack.com/docs/content-managers/timeline/preview-content-across-a-timeline), and [Visual Editor](https://www.contentstack.com/docs/content-managers/visual-editor/about-visual-editor) work in Contentstack for editors and content managers. @@ -11,7 +11,7 @@ See how [Live Preview](https://www.contentstack.com/docs/content-managers/author - **Live Preview** — Preview entries in the stack while your site loads inside the preview panel. - **Timeline** — Time-based preview (how the site looks on future dates). Your integration pattern is the same as Live Preview from the app’s perspective; the parent context is still a preview iframe. In code, `config.windowType` can reflect a preview context that includes Timeline ([see `config` / `windowType`](docs/live-preview-configs.md#config)). -- **Visual Builder** — WYSIWYG editing with the site in an iframe. Use `mode: "builder"` so “Start Editing” targets Visual Builder; the SDK still works when the same site is opened in Live Preview ([`mode`](docs/live-preview-configs.md#mode)). +- **Visual Editor** — WYSIWYG editing with the site in an iframe. Use `mode: "builder"` so “Start Editing” targets Visual Editor; the SDK still works when the same site is opened in Live Preview ([`mode`](docs/live-preview-configs.md#mode)). - **Composable Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is the visual composition experience for building experiences from components and content. Use this package when your front end needs the same live preview and stack-driven editing hooks as in Live Preview; follow Studio and Live Preview setup docs together for your stack. **Integrators:** In hosted preview, the platform loads your site in an iframe; this SDK talks to the parent window. When you open the site outside Contentstack (`windowType: independent`), behavior follows the [config](docs/live-preview-configs.md#config) rules in the reference doc. @@ -70,7 +70,7 @@ Full tables and examples: **[docs/live-preview-configs.md](docs/live-preview-con - [`ssr`](docs/live-preview-configs.md#ssr) - [`mode`](docs/live-preview-configs.md#mode) (`preview` vs `builder`) - [`editButton`](docs/live-preview-configs.md#editbutton) -- [`editInVisualBuilderButton`](docs/live-preview-configs.md#editinvisualbuilderbutton) (Start Editing outside Visual Builder) +- [`editInVisualBuilderButton`](docs/live-preview-configs.md#editinvisualbuilderbutton) (Start Editing outside Visual Editor) - [`cleanCslpOnProduction`](docs/live-preview-configs.md#cleancslponproduction) - [`stackDetails`](docs/live-preview-configs.md#stackdetails) ([`apiKey`](docs/live-preview-configs.md#apikey), [`environment`](docs/live-preview-configs.md#environment)) - [`clientUrlParams`](docs/live-preview-configs.md#clienturlparams) — [NA](docs/live-preview-configs.md#na-config) / [EU](docs/live-preview-configs.md#eu-config) @@ -81,7 +81,7 @@ Full tables and examples: **[docs/live-preview-configs.md](docs/live-preview-con - [`onLiveEdit`](docs/live-preview-configs.md#onliveeditcallback---void) - [`onEntryChange`](docs/live-preview-configs.md#onentrychangecallback---void) - [`hash`](docs/live-preview-configs.md#hash) -- [`config`](docs/live-preview-configs.md#config) (includes `windowType`: Live Preview / Timeline preview, Visual Builder, or independent) +- [`config`](docs/live-preview-configs.md#config) (includes `windowType`: Live Preview / Timeline preview, Visual Editor, or independent) The [configs table of contents](docs/live-preview-configs.md#contentstack-live-preview-utils-sdk-configs) also lists `setConfigFromParams` and `getGatsbyDataFormat` for deeper workflows. @@ -110,7 +110,7 @@ The [configs table of contents](docs/live-preview-configs.md#contentstack-live-p - [Implementing Live Preview (course)](https://www.contentstack.com/academy/courses/implementing-live-preview) - [Contentstack Live Preview under the hood](https://www.contentstack.com/academy/content/contentstack-live-preview-under-the-hood) - [Understanding Timeline](https://www.contentstack.com/academy/content/understanding-timeline) -- [Understanding Visual Builder](https://www.contentstack.com/academy/content/understanding-visual-builder) +- [Understanding Visual Editor](https://www.contentstack.com/academy/content/understanding-visual-builder) ## Advanced: stripping the SDK at build time From 6e1572f79335097825997d3e3473f8dcd3b62fa7 Mon Sep 17 00:00:00 2001 From: hiteshshetty-dev Date: Mon, 30 Mar 2026 18:41:17 +0530 Subject: [PATCH 3/8] docs(mustache): sync README template with published README - Expand main.mustache to match README (badges, contexts, docs links, Academy) - Use {{packageVersion}} in CDN snippet; pin wording matches README - Remove unused currentYear from mustache.ts DATA Made-with: Cursor --- main.mustache | 125 +++++++++++++++++++++++++++++++++++++------------- mustache.ts | 1 - 2 files changed, 94 insertions(+), 32 deletions(-) diff --git a/main.mustache b/main.mustache index 6fc64f64..07d59533 100644 --- a/main.mustache +++ b/main.mustache @@ -1,60 +1,123 @@ -# Contentstack Live Preview Utils SDK +# @contentstack/live-preview-utils -Contentstack is a headless CMS with an API-first approach. It is a CMS that developers can use to build powerful cross-platform applications in their favorite languages. Build your application frontend, and Contentstack will take care of the rest. +[![npm](https://img.shields.io/npm/v/@contentstack/live-preview-utils.svg)](https://www.npmjs.com/package/@contentstack/live-preview-utils) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -Contentstack provides the Live Preview Utils SDK to establish a communication channel between the various Contentstack SDKs and your website, transmitting live changes to the preview pane. [Read More](https://www.contentstack.com/docs/content-managers/live-preview/). +The **Live Preview Utils** package runs in your website and opens a communication channel between the page (often inside a Contentstack preview iframe) and the platform. It powers live content updates, edit controls, and Visual Editor UI in the preview surface via messaging—not a replacement for the Contentstack delivery SDKs, but the client bridge for preview and Visual Editor experiences. -# Installation +See how [Live Preview](https://www.contentstack.com/docs/content-managers/author-content/about-live-preview), [Timeline](https://www.contentstack.com/docs/content-managers/timeline/preview-content-across-a-timeline), and [Visual Editor](https://www.contentstack.com/docs/content-managers/visual-editor/about-visual-editor) work in Contentstack for editors and content managers. -To install the package via npm, use the following command: +## Where this SDK runs + +- **Live Preview** — Preview entries in the stack while your site loads inside the preview panel. +- **Timeline** — Time-based preview (how the site looks on future dates). Your integration pattern is the same as Live Preview from the app’s perspective; the parent context is still a preview iframe. In code, `config.windowType` can reflect a preview context that includes Timeline ([see `config` / `windowType`](docs/live-preview-configs.md#config)). +- **Visual Editor** — WYSIWYG editing with the site in an iframe. Use `mode: "builder"` so “Start Editing” targets Visual Editor; the SDK still works when the same site is opened in Live Preview ([`mode`](docs/live-preview-configs.md#mode)). +- **Composable Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is the visual composition experience for building experiences from components and content. Use this package when your front end needs the same live preview and stack-driven editing hooks as in Live Preview; follow Studio and Live Preview setup docs together for your stack. + +**Integrators:** In hosted preview, the platform loads your site in an iframe; this SDK talks to the parent window. When you open the site outside Contentstack (`windowType: independent`), behavior follows the [config](docs/live-preview-configs.md#config) rules in the reference doc. + +## Requirements + +- **Browser:** Initialize only on the client (`window` must exist). Server-only bundles should not call `init` during SSR. +- **SSR vs CSR:** Defaults assume SSR-friendly behavior. For **client-side rendering**, pass [`stackSdk`](docs/live-preview-configs.md#stacksdk) and set [`ssr: false`](docs/live-preview-configs.md#ssr) as described in the config reference. + +## Installation ```bash npm install @contentstack/live-preview-utils ``` -Alternatively, if you want to include the package directly in your website HTML code, use the following command: +### Load from a CDN (advanced) + +Pin the version to match your app (update `{{packageVersion}}` when you upgrade): ```html - ``` -> [!NOTE] -> This step involves incorporating the package into your HTML code and initializing it, eliminating the need for re-initialization in the subsequent step. - -# Initializing the SDK +> [!TIP] +> If you bootstrap with the snippet above, skip a second `init` from your app bundle on the same page. -### Live Preview Utils +## Quick start -Since the Live Preview Utils SDK is responsible for communication, you need to only initialize it. -Use the following command to initialize the SDK: +[`init`](docs/live-preview-configs.md#initconfig-iconfig) returns a `Promise` that resolves to `{ livePreview, visualBuilder }`. Calling `init` again returns the existing instance and logs a warning. ```javascript import ContentstackLivePreview from "@contentstack/live-preview-utils"; -ContentstackLivePreview.init({ - stackDetails: { - apiKey: "your-stack-api-key", - }, +const { livePreview, visualBuilder } = await ContentstackLivePreview.init({ + stackDetails: { + apiKey: "your-stack-api-key", + }, }); ``` +## Configuration + +Full tables and examples: **[docs/live-preview-configs.md](docs/live-preview-configs.md)**. -# License +**`init` options** -MIT License +- [`enable`](docs/live-preview-configs.md#enable) +- [`ssr`](docs/live-preview-configs.md#ssr) +- [`mode`](docs/live-preview-configs.md#mode) (`preview` vs `builder`) +- [`editButton`](docs/live-preview-configs.md#editbutton) +- [`editInVisualBuilderButton`](docs/live-preview-configs.md#editinvisualbuilderbutton) (Start Editing outside Visual Editor) +- [`cleanCslpOnProduction`](docs/live-preview-configs.md#cleancslponproduction) +- [`stackDetails`](docs/live-preview-configs.md#stackdetails) ([`apiKey`](docs/live-preview-configs.md#apikey), [`environment`](docs/live-preview-configs.md#environment)) +- [`clientUrlParams`](docs/live-preview-configs.md#clienturlparams) — [NA](docs/live-preview-configs.md#na-config) / [EU](docs/live-preview-configs.md#eu-config) +- [`stackSdk`](docs/live-preview-configs.md#stacksdk) -Copyright © 2021-{{currentYear}} [Contentstack](https://www.contentstack.com/). All Rights Reserved +**Methods and properties** -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: +- [`onLiveEdit`](docs/live-preview-configs.md#onliveeditcallback---void) +- [`onEntryChange`](docs/live-preview-configs.md#onentrychangecallback---void) +- [`hash`](docs/live-preview-configs.md#hash) +- [`config`](docs/live-preview-configs.md#config) (includes `windowType`: Live Preview / Timeline preview, Visual Editor, or independent) + +The [configs table of contents](docs/live-preview-configs.md#contentstack-live-preview-utils-sdk-configs) also lists `setConfigFromParams` and `getGatsbyDataFormat` for deeper workflows. + +## Documentation and learning + +**Developers** + +- [Set up Live Preview for your website](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-your-website) +- [How Live Preview works](https://www.contentstack.com/docs/developers/set-up-live-preview/how-live-preview-works) +- [Preview API](https://www.contentstack.com/docs/developers/set-up-timeline/preview-api) +- [Set up Timeline for your website](https://www.contentstack.com/docs/developers/set-up-timeline/set-up-timeline-for-your-website) + +**Content managers** + +- [About Live Preview](https://www.contentstack.com/docs/content-managers/author-content/about-live-preview) +- [Preview content across a Timeline](https://www.contentstack.com/docs/content-managers/timeline/preview-content-across-a-timeline) +- [About Visual Editor](https://www.contentstack.com/docs/content-managers/visual-editor/about-visual-editor) + +**Studio** + +- [Studio](https://www.contentstack.com/docs/studio) +- [Get started with Studio](https://www.contentstack.com/docs/studio/get-started-with-studio) + +**Academy** + +- [Implementing Live Preview (course)](https://www.contentstack.com/academy/courses/implementing-live-preview) +- [Contentstack Live Preview under the hood](https://www.contentstack.com/academy/content/contentstack-live-preview-under-the-hood) +- [Understanding Timeline](https://www.contentstack.com/academy/content/understanding-timeline) +- [Understanding Visual Editor](https://www.contentstack.com/academy/content/understanding-visual-builder) + +## Advanced: stripping the SDK at build time + +> [!NOTE] +> Set `PURGE_PREVIEW_SDK` or `REACT_APP_PURGE_PREVIEW_SDK` to `"true"` at build time to swap the default export for a light stub so preview code is not bundled for production. -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. +## Resources -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +- **Source:** [github.com/contentstack/live-preview-sdk](https://github.com/contentstack/live-preview-sdk) +- **Typed API (local):** `npm run docs` diff --git a/mustache.ts b/mustache.ts index 2c34b574..9229f2bc 100644 --- a/mustache.ts +++ b/mustache.ts @@ -11,7 +11,6 @@ const MUSTACHE_MAIN_DIR = './main.mustache'; */ const DATA = { packageVersion: packageJson.version, - currentYear: new Date().getFullYear(), }; function generateReadMe() { From 82f879100c5f83ff8a01fded7a1a7d0412e51ba9 Mon Sep 17 00:00:00 2001 From: hiteshshetty-dev Date: Mon, 30 Mar 2026 18:58:33 +0530 Subject: [PATCH 4/8] docs(readme): rename Composable Studio bullet to Studio Made-with: Cursor --- README.md | 2 +- main.mustache | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4b3c5227..1fd90bd1 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ See how [Live Preview](https://www.contentstack.com/docs/content-managers/author - **Live Preview** — Preview entries in the stack while your site loads inside the preview panel. - **Timeline** — Time-based preview (how the site looks on future dates). Your integration pattern is the same as Live Preview from the app’s perspective; the parent context is still a preview iframe. In code, `config.windowType` can reflect a preview context that includes Timeline ([see `config` / `windowType`](docs/live-preview-configs.md#config)). - **Visual Editor** — WYSIWYG editing with the site in an iframe. Use `mode: "builder"` so “Start Editing” targets Visual Editor; the SDK still works when the same site is opened in Live Preview ([`mode`](docs/live-preview-configs.md#mode)). -- **Composable Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is the visual composition experience for building experiences from components and content. Use this package when your front end needs the same live preview and stack-driven editing hooks as in Live Preview; follow Studio and Live Preview setup docs together for your stack. +- **Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is the visual composition experience for building experiences from components and content. Use this package when your front end needs the same live preview and stack-driven editing hooks as in Live Preview; follow Studio and Live Preview setup docs together for your stack. **Integrators:** In hosted preview, the platform loads your site in an iframe; this SDK talks to the parent window. When you open the site outside Contentstack (`windowType: independent`), behavior follows the [config](docs/live-preview-configs.md#config) rules in the reference doc. diff --git a/main.mustache b/main.mustache index 07d59533..8f1a30c4 100644 --- a/main.mustache +++ b/main.mustache @@ -12,7 +12,7 @@ See how [Live Preview](https://www.contentstack.com/docs/content-managers/author - **Live Preview** — Preview entries in the stack while your site loads inside the preview panel. - **Timeline** — Time-based preview (how the site looks on future dates). Your integration pattern is the same as Live Preview from the app’s perspective; the parent context is still a preview iframe. In code, `config.windowType` can reflect a preview context that includes Timeline ([see `config` / `windowType`](docs/live-preview-configs.md#config)). - **Visual Editor** — WYSIWYG editing with the site in an iframe. Use `mode: "builder"` so “Start Editing” targets Visual Editor; the SDK still works when the same site is opened in Live Preview ([`mode`](docs/live-preview-configs.md#mode)). -- **Composable Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is the visual composition experience for building experiences from components and content. Use this package when your front end needs the same live preview and stack-driven editing hooks as in Live Preview; follow Studio and Live Preview setup docs together for your stack. +- **Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is the visual composition experience for building experiences from components and content. Use this package when your front end needs the same live preview and stack-driven editing hooks as in Live Preview; follow Studio and Live Preview setup docs together for your stack. **Integrators:** In hosted preview, the platform loads your site in an iframe; this SDK talks to the parent window. When you open the site outside Contentstack (`windowType: independent`), behavior follows the [config](docs/live-preview-configs.md#config) rules in the reference doc. From 52baa79dbd9345d4cc31cefce2714395ed111eb3 Mon Sep 17 00:00:00 2001 From: hiteshshetty-dev Date: Tue, 31 Mar 2026 10:41:00 +0530 Subject: [PATCH 5/8] docs: update Timeline and Studio descriptions in README and main.mustache --- README.md | 6 ++---- main.mustache | 6 ++---- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1fd90bd1..73905e11 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,9 @@ See how [Live Preview](https://www.contentstack.com/docs/content-managers/author ## Where this SDK runs - **Live Preview** — Preview entries in the stack while your site loads inside the preview panel. -- **Timeline** — Time-based preview (how the site looks on future dates). Your integration pattern is the same as Live Preview from the app’s perspective; the parent context is still a preview iframe. In code, `config.windowType` can reflect a preview context that includes Timeline ([see `config` / `windowType`](docs/live-preview-configs.md#config)). +- **Timeline** — Time-based preview (how the site looks on future dates and scheduled updates). Use the same Live Preview setup on your site; see the Timeline docs below for stack-side behavior. - **Visual Editor** — WYSIWYG editing with the site in an iframe. Use `mode: "builder"` so “Start Editing” targets Visual Editor; the SDK still works when the same site is opened in Live Preview ([`mode`](docs/live-preview-configs.md#mode)). -- **Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is the visual composition experience for building experiences from components and content. Use this package when your front end needs the same live preview and stack-driven editing hooks as in Live Preview; follow Studio and Live Preview setup docs together for your stack. - -**Integrators:** In hosted preview, the platform loads your site in an iframe; this SDK talks to the parent window. When you open the site outside Contentstack (`windowType: independent`), behavior follows the [config](docs/live-preview-configs.md#config) rules in the reference doc. +- **Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is Contentstack’s visual experience builder: you structure pages from reusable components, bind CMS data, and manage compositions. It is designed to work with [Live Preview and Visual Editor](https://www.contentstack.com/docs/studio/live-preview-and-visual-editing-with-studio) on your connected site (layout in Studio, real-time preview, then field-level edits in Visual Editor). ## Requirements diff --git a/main.mustache b/main.mustache index 8f1a30c4..6e0f440b 100644 --- a/main.mustache +++ b/main.mustache @@ -10,11 +10,9 @@ See how [Live Preview](https://www.contentstack.com/docs/content-managers/author ## Where this SDK runs - **Live Preview** — Preview entries in the stack while your site loads inside the preview panel. -- **Timeline** — Time-based preview (how the site looks on future dates). Your integration pattern is the same as Live Preview from the app’s perspective; the parent context is still a preview iframe. In code, `config.windowType` can reflect a preview context that includes Timeline ([see `config` / `windowType`](docs/live-preview-configs.md#config)). +- **Timeline** — Time-based preview (how the site looks on future dates and scheduled updates). Use the same Live Preview setup on your site; see the Timeline docs below for stack-side behavior. - **Visual Editor** — WYSIWYG editing with the site in an iframe. Use `mode: "builder"` so “Start Editing” targets Visual Editor; the SDK still works when the same site is opened in Live Preview ([`mode`](docs/live-preview-configs.md#mode)). -- **Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is the visual composition experience for building experiences from components and content. Use this package when your front end needs the same live preview and stack-driven editing hooks as in Live Preview; follow Studio and Live Preview setup docs together for your stack. - -**Integrators:** In hosted preview, the platform loads your site in an iframe; this SDK talks to the parent window. When you open the site outside Contentstack (`windowType: independent`), behavior follows the [config](docs/live-preview-configs.md#config) rules in the reference doc. +- **Studio** — [Contentstack Studio](https://www.contentstack.com/docs/studio) is Contentstack’s visual experience builder: you structure pages from reusable components, bind CMS data, and manage compositions. It is designed to work with [Live Preview and Visual Editor](https://www.contentstack.com/docs/studio/live-preview-and-visual-editing-with-studio) on your connected site (layout in Studio, real-time preview, then field-level edits in Visual Editor). ## Requirements From e8d6ba34ecd9ec3c58988e5d82c5efbd52f4fc96 Mon Sep 17 00:00:00 2001 From: hiteshshetty-dev Date: Tue, 31 Mar 2026 18:12:15 +0530 Subject: [PATCH 6/8] docs: update README and main.mustache to include Studio in descriptions --- README.md | 6 +++--- main.mustache | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 73905e11..bf0d17b8 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ The **Live Preview Utils** package runs in your website and opens a communication channel between the page (often inside a Contentstack preview iframe) and the platform. It powers live content updates, edit controls, and Visual Editor UI in the preview surface via messaging—not a replacement for the Contentstack delivery SDKs, but the client bridge for preview and Visual Editor experiences. -See how [Live Preview](https://www.contentstack.com/docs/content-managers/author-content/about-live-preview), [Timeline](https://www.contentstack.com/docs/content-managers/timeline/preview-content-across-a-timeline), and [Visual Editor](https://www.contentstack.com/docs/content-managers/visual-editor/about-visual-editor) work in Contentstack for editors and content managers. +See how [Live Preview](https://www.contentstack.com/docs/content-managers/author-content/about-live-preview), [Timeline](https://www.contentstack.com/docs/content-managers/timeline/preview-content-across-a-timeline), [Visual Editor](https://www.contentstack.com/docs/content-managers/visual-editor/about-visual-editor), and [Studio](https://www.contentstack.com/docs/studio) work in Contentstack for editors and content managers. ## Where this SDK runs @@ -46,12 +46,12 @@ Pin the version to match your app (update `4.3.0` when you upgrade): ## Quick start -[`init`](docs/live-preview-configs.md#initconfig-iconfig) returns a `Promise` that resolves to `{ livePreview, visualBuilder }`. Calling `init` again returns the existing instance and logs a warning. +[`init`](docs/live-preview-configs.md#initconfig-iconfig) returns a `Promise` that resolves when the SDK is ready. Call it once; subsequent calls reuse the same in-memory instance and log a warning. **Use the static APIs** in [docs/live-preview-configs.md](docs/live-preview-configs.md) (for example [`onLiveEdit`](docs/live-preview-configs.md#onliveeditcallback---void), [`hash`](docs/live-preview-configs.md#hash), [`config`](docs/live-preview-configs.md#config))—we do not recommend destructuring or otherwise using the value returned from `init`. ```javascript import ContentstackLivePreview from "@contentstack/live-preview-utils"; -const { livePreview, visualBuilder } = await ContentstackLivePreview.init({ +await ContentstackLivePreview.init({ stackDetails: { apiKey: "your-stack-api-key", }, diff --git a/main.mustache b/main.mustache index 6e0f440b..2708829f 100644 --- a/main.mustache +++ b/main.mustache @@ -5,7 +5,7 @@ The **Live Preview Utils** package runs in your website and opens a communication channel between the page (often inside a Contentstack preview iframe) and the platform. It powers live content updates, edit controls, and Visual Editor UI in the preview surface via messaging—not a replacement for the Contentstack delivery SDKs, but the client bridge for preview and Visual Editor experiences. -See how [Live Preview](https://www.contentstack.com/docs/content-managers/author-content/about-live-preview), [Timeline](https://www.contentstack.com/docs/content-managers/timeline/preview-content-across-a-timeline), and [Visual Editor](https://www.contentstack.com/docs/content-managers/visual-editor/about-visual-editor) work in Contentstack for editors and content managers. +See how [Live Preview](https://www.contentstack.com/docs/content-managers/author-content/about-live-preview), [Timeline](https://www.contentstack.com/docs/content-managers/timeline/preview-content-across-a-timeline), [Visual Editor](https://www.contentstack.com/docs/content-managers/visual-editor/about-visual-editor), and [Studio](https://www.contentstack.com/docs/studio) work in Contentstack for editors and content managers. ## Where this SDK runs @@ -46,12 +46,12 @@ Pin the version to match your app (update `{{packageVersion}}` when you upgrade) ## Quick start -[`init`](docs/live-preview-configs.md#initconfig-iconfig) returns a `Promise` that resolves to `{ livePreview, visualBuilder }`. Calling `init` again returns the existing instance and logs a warning. +[`init`](docs/live-preview-configs.md#initconfig-iconfig) returns a `Promise` that resolves when the SDK is ready. Call it once; subsequent calls reuse the same in-memory instance and log a warning. **Use the static APIs** in [docs/live-preview-configs.md](docs/live-preview-configs.md) (for example [`onLiveEdit`](docs/live-preview-configs.md#onliveeditcallback---void), [`hash`](docs/live-preview-configs.md#hash), [`config`](docs/live-preview-configs.md#config))—we do not recommend destructuring or otherwise using the value returned from `init`. ```javascript import ContentstackLivePreview from "@contentstack/live-preview-utils"; -const { livePreview, visualBuilder } = await ContentstackLivePreview.init({ +await ContentstackLivePreview.init({ stackDetails: { apiKey: "your-stack-api-key", }, From f0b121166ad62aa17a0d2866682b1db54edecf9b Mon Sep 17 00:00:00 2001 From: hiteshshetty-dev Date: Tue, 31 Mar 2026 18:22:17 +0530 Subject: [PATCH 7/8] docs: update initialization method in README and main.mustache to remove Promise usage --- README.md | 10 +++++++--- main.mustache | 10 +++++++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index bf0d17b8..1bf3e0cd 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Pin the version to match your app (update `4.3.0` when you upgrade):