Skip to content

Issue 36376 nextjs experiments example - #36490

Merged
erickgonzalez merged 11 commits into
mainfrom
issue-36376-nextjs-experiments-example
Jul 13, 2026
Merged

Issue 36376 nextjs experiments example#36490
erickgonzalez merged 11 commits into
mainfrom
issue-36376-nextjs-experiments-example

Conversation

@erickgonzalez

@erickgonzalez erickgonzalez commented Jul 9, 2026

Copy link
Copy Markdown
Member
  • Updated all references to new starter 20260630
  • Updated the example nextjs-analytics-experiments to only experiments nextjs-experiments since Analytics and Experiments now use diff infrastructures.

This PR fixes: #36376

This PR fixes: #36376

- **feat(experiments): enhance Next.js example with experiments integration**
  - Updated `dotcms.config.ts` to default `NEXT_PUBLIC_DOTCMS_HOST` and `NEXT_PUBLIC_DOTCMS_EXPERIMENTS_KEY` to empty strings (`""`) for stricter typing and improved fallback handling.
  - Integrated `@dotcms/experiments` with the `Page.tsx` view, conditionally wrapping content with `withExperiments` based on the presence of the API key.
  - Added `redirectFn` to utilize Next.js `replace()` for seamless navigation during experiments.
  - Bumped `CUSTOM_STARTER_URL` in Docker Compose configurations to use the latest starter version (`20260630`).
  - Updated README for `dotcms.config.ts` to reflect renamed `apiKey` and clarified fallback behavior for experiments.

ref: #36376
Signed-off-by: erickgonzalez <erick.gonzalez@dotcms.com>
…ments documentation**

- Added a **TL;DR section** to the README with concise steps for setting up and running the example with A/B experiments.
- Documented how to enable A/B experiments using the `withExperiments` HOC and detailed its integration within `Page.tsx`.
- Explained conditional wrapping of `DotCMSLayoutBody` with `withExperiments`, based on the presence of an API key.
- Noted key features of `withExperiments` such as client-side redirects using `redirectFn` and the experiment-aware rendering process.
- Updated README and code comments to clarify requirements around experiments, including the use of environment variables.

ref: #36376
Signed-off-by: erickgonzalez <erick.gonzalez@dotcms.com>
- Removed the detailed explanation of the Next.js + dotCMS architecture from the example's README.
  - Excluded content included file structure breakdown, advanced integration steps, and in-depth code examples.
  - Simplified the README for a more streamlined developer onboarding experience.
- Migrated advanced topics to external documentation resources.
- Improved focus on core concepts (e.g., Universal Visual Editor, experiments).
- Ensured key links to official resources (e.g., dotCMS docs, npm packages) were retained.

ref: #36376
Signed-off-by: erickgonzalez <erick.gonzalez@dotcms.com>
…on**

- Bumped `CUSTOM_STARTER_URL` across all Docker Compose files and related documentation to reference the latest starter version (`20260630`).
- Updated examples in the following sections:
  - Single-node, cluster-mode, push-publish, Redis, and debug-mode configurations.
  - Developer environment, OpenSearch Dashboard integration, demo site, and database dump loading examples.
- Ensured consistency in accompanying README files to match updated URL references.

ref: #36376
Signed-off-by: erickgonzalez <erick.gonzalez@dotcms.com>
@github-actions github-actions Bot added Area : Backend PR changes Java/Maven backend code Area : CLI PR changes dotCMS CLI code Area : Documentation PR changes documentation files labels Jul 9, 2026
@claude

claude Bot commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

Claude finished @erickgonzalez's task in 2m 28s —— View job


Code Review — PR #36490 (Next.js experiments example)

  • Gather context
  • Review changed files
  • Post review feedback

This PR is scoped to the examples/ Next.js app rewrite plus starter version bumps (20260630) across docker-compose/README files. No Java/backend code changed despite the labels, so the backend-convention checks don't apply here. Review focuses on the new example code.

New Issues

  • 🟡 Medium: examples/nextjs-experiments/src/views/Page.tsx:25-30withExperiments(DotCMSLayoutBody, …) is called inside the component body, so it produces a new component reference on every render. React treats a changed component type at the same position as a full unmount/remount of the subtree, which can remount the layout body (state loss, flicker, and potentially re-firing experiment assignment) on each render. Wrap it in useMemo keyed on [replace] (and gate on experimentsConfig.apiKey) so the wrapped component is stable across renders. Fix this →

  • 🟡 Medium: examples/nextjs-experiments/.env.local.example:5NODE_TLS_REJECT_UNAUTHORIZED=0 ships in the example env template. This globally disables TLS certificate verification for the Node process. Even in an example, this teaches an insecure default and can silently mask cert misconfiguration. Recommend removing it or gating it behind a clearly-commented "local self-signed only" note.

  • 🟡 Medium: examples/nextjs-experiments/src/app/blog/post/[[...slug]]/page.tsx:19,41const path = slug?.[0] only uses the first path segment. For a catch-all route ([[...slug]]), a nested post URL like /blog/post/2024/my-post collapses to fetching /blog/post/2024, dropping the rest. If nested post slugs are ever valid, use slug?.join("/") like getPath does in the main [[...slug]]/page.tsx. (Assumption: post slugs may be multi-segment. What to verify: whether dotCMS post URLs are always single-segment in the demo starter.)

Notes (non-blocking)

  • getDotCMSPage (src/utils/getDotCMSPage.ts:34) swallows all errors into { error } — that's intentional and handled by the isPageError guards, so it's fine. Just confirm real network failures still surface a usable status via getErrorStatus (it returns undefined when the SDK error has no status field, which then renders a generic error page — acceptable for an example).

Overall this is clean example/demo code. The withExperiments remount issue is the only one I'd recommend addressing before merge since it affects the headline feature (experiments) this example is meant to showcase.
· issue-36376-nextjs-experiments-example

…arity in experiments example**

- **Enhanced Experiments Configuration:**
  - Updated `dotcms.config.ts` with clearer comments on the usage of environment variables, including fallback behavior.
  - Explicitly documented required (`hostname`, `apiKey`) and optional (`debug` mode) environment variables.

- **Error Handling Improvements:**
  - Added a `catch` block in `BlogListingPage.tsx` to handle API call failures gracefully.
    - Logs an error message (`'Blog search failed'`) to aid in debugging.
    - Ensures the `setSearchResults` value does not retain stale data by resetting it to `null`.

- **Code Cleanup:**
  - Removed unnecessary `console.log` statement from `Page.tsx`.

- **Utility Enhancement:**
  - Updated `formatDate` utility to ensure it returns an empty string (`""`) for missing or invalid dates, avoiding rendering issues like `"Invalid Date"` in the UI.

ref: #36376
Signed-off-by: erickgonzalez <erick.gonzalez@dotcms.com>
- Updated `@dotcms/experiments` dependency in `examples/nextjs-experiments/package.json` to use the `next` version for consistency with other dotCMS packages.
- Ensures alignment with the latest experimental features and fixes across all dependencies.

ref: #36376
Signed-off-by: erickgonzalez <erick.gonzalez@dotcms.com>
…mprove logging**

- Updated `getDotCMSPage` utility to accept an optional `variantName` parameter for fetching experiment-specific page content.
- Modified `SlugPageProps` to include `searchParams` and enabled passing the `variantName` to the `generateMetadata` and `Home` functions.
- Enhanced `page.tsx` to log `variantName` and improve debugging for dynamic page asset retrieval.
- Added logging in `getDotCMSPage` to trace API calls with `path` and `variantName`.

ref: #36376
Signed-off-by: erickgonzalez <erick.gonzalez@dotcms.com>
…tion links**

- Corrected mislabeled steps in the setup guide, updating references to configuration steps for better alignment with content structure.
- Fixed broken navigation links in the README, ensuring references accurately direct to corresponding sections.
- Rephrased instructions for setting up `.env.local` and API keys to enhance clarity.
- Streamlined guide introduction by replacing redundant sentences with concise descriptions.
- Added details about fetching a specific experiment variant in the `getDotCMSPage` utility to the documentation.

ref: #36376
Signed-off-by: erickgonzalez <erick.gonzalez@dotcms.com>
…on defaults**

- **Removed Unnecessary Logging:**
  - Removed redundant `console.log` statements from `Page.tsx` and `getDotCMSPage` to declutter logs and improve code readability.

- **Enhanced Fallback Configuration:**
  - Updated `next.config.ts` to use a default URL fallback (`http://localhost:8080`) when `dotCMSHost` is not defined, ensuring smoother local development and preventing crashes caused by invalid configuration.

- **Updated Rewrites:**
  - Modified rewrite `destination` paths in `next.config.ts` to use the resolved `resolvedHost` value for better consistency with the new fallback behavior.

ref: #36376
Signed-off-by: erickgonzalez <erick.gonzalez@dotcms.com>
@erickgonzalez
erickgonzalez added this pull request to the merge queue Jul 13, 2026
@mergify

mergify Bot commented Jul 13, 2026

Copy link
Copy Markdown

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

  • Queue this pull request

Merged via the queue into main with commit 2b87567 Jul 13, 2026
62 checks passed
@erickgonzalez
erickgonzalez deleted the issue-36376-nextjs-experiments-example branch July 13, 2026 21:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AI: Safe To Rollback Area : Backend PR changes Java/Maven backend code Area : CLI PR changes dotCMS CLI code Area : Documentation PR changes documentation files

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

Improve @dotcms/experiments SDK docs and add Next.js analytics + experiments example

2 participants