Create Developer Onboarding Guide for Next.js with UVE#33941
Merged
Conversation
…y resolver - Removed the DotStarterResolver and associated tests, simplifying the onboarding process. - Introduced a new onboarding structure with detailed steps, commands, and troubleshooting sections. - Updated the component's HTML and SCSS for a modernized layout and improved user experience. - Enhanced progress tracking and local storage management for user onboarding steps. - Adjusted module imports to include necessary PrimeNG components for the new design.
- Moved the import of MarkdownModule to the top of the dot-starter.component.spec.ts and dot-starter.module.ts files for improved organization and consistency across the codebase.
- Introduced a new progress tracking section with a current step display and a reset button. - Updated the HTML structure for improved accessibility and user experience. - Enhanced SCSS styles for a modern look, including a sticky progress bar and responsive layout. - Added new TypeScript getters for current step information and total steps, improving the onboarding logic. - Integrated PrimeNG Knob component for visual progress representation.
…yles - Updated HTML structure to enhance accessibility and user experience by introducing a new content wrapper. - Modified SCSS styles for improved layout, including a flexbox design for better responsiveness. - Simplified progress tracking display and adjusted component alignment for a cleaner look. - Removed unnecessary elements and streamlined the code for better maintainability.
- Replaced the status display with a PrimeNG tag component for improved visual feedback on step completion. - Removed legacy SCSS styles related to the status display to streamline the code. - Added TagModule import to the module for the new component integration. - Adjusted styles for better alignment and responsiveness in the onboarding component.
- Updated HTML structure to improve accessibility and user experience, including a new header template for accordion tabs. - Adjusted SCSS styles for better typography and layout consistency, including new styles for headings and improved spacing. - Simplified the component structure by removing unnecessary elements and enhancing the visual presentation of steps and notes.
- Upgraded ngx-markdown to version 20.1.0 for improved functionality. - Updated prismjs to version 1.30.0, enhancing syntax highlighting capabilities. - Added PrismJS styles and scripts to the dotcms-ui project for better code presentation. - Refined HTML structure in the onboarding component for improved readability and maintainability. - Enhanced SCSS styles for better layout and responsiveness in the onboarding component.
- Introduced a new ButtonCopyComponent for clipboard copy functionality, improving user experience. - Updated dot-starter.component.html to integrate the new clipboard feature within the onboarding process. - Added clipboard.js dependency to package.json for enhanced clipboard operations. - Refined HTML structure and styles in dot-starter.component.html for better layout and responsiveness. - Updated dot-starter.module.ts to include the new ButtonCopyComponent and TooltipModule for improved UI interactions.
- Simplified HTML structure by consolidating command and troubleshooting sections for better readability. - Updated SCSS styles to improve layout responsiveness and visual hierarchy, including adjustments to flex properties. - Replaced deprecated description fields with explanation fields in TypeScript interfaces for clarity. - Enhanced markdown rendering for commands and troubleshooting items to improve user experience during onboarding.
… rebuild performance
- Commented out legacy title and description fields in the HTML for future reference. - Updated accordion component to set the active index for better user experience. - Improved command display by restructuring the command explanation into title and description fields. - Enhanced SCSS styles for better layout, including new styles for headings and command descriptions. - Added margin adjustments to ensure consistent spacing in the onboarding steps.
…larity and security
…arity and relevance
…h scrolling to next step
Legal RiskThe following dependencies were released under a license that RecommendationWhile merging is not directly blocked, it's best to pause and consider what it means to use this license before continuing. If you are unsure, reach out to your security team or Semgrep admin to address this issue. MPL-2.0 |
…n and visual editing instructions
…tion and improved UI elements
…utomatic undo for completed steps
…nboarding component HTML
oidacra
approved these changes
Jan 27, 2026
AfaqJaved
approved these changes
Jan 27, 2026
rjvelazco
approved these changes
Jan 27, 2026
...tcms-ui/src/app/portlets/dot-starter/components/onboarding-dev/onboarding-dev.component.scss
Show resolved
Hide resolved
...i/src/app/portlets/dot-starter/components/onboarding-author/onboarding-author.component.html
Outdated
Show resolved
Hide resolved
…s to version 1.30.0
…ructure and permissions handling
…roved test structure and readability
…and menu actions validation
…y and enhance unit tests for profile selection
![semgrep-code-dotcms-test[bot]](https://avatars.githubusercontent.com/u/1005263?s=60&v=4){kind=small}
core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter.component.spec.ts
Show resolved
Hide resolved
core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter.component.spec.ts
Show resolved
Hide resolved
PRs linked to this issue |
github-merge-queue bot
pushed a commit
that referenced
this pull request
Jan 29, 2026
## Summary Remove unused PrismJS Okaidia theme CSS dependency from the dotCMS UI build configuration. ## Changes Made ### Frontend - Removed `prismjs/themes/prism-okaidia.css` from Angular build styles configuration in `core-web/apps/dotcms-ui/project.json:64` - Clean up unused CSS dependency to reduce bundle size ### Configuration - Updated Nx project configuration to remove obsolete style import ## Technical Details The Okaidia theme CSS from PrismJS was included in the global styles array but is no longer used in the application. This change removes the unused dependency reference from the build configuration, which will result in a slightly smaller production bundle and cleaner build output. ## Breaking Changes None ## Testing - [ ] Unit tests added/updated - N/A (configuration-only change) - [ ] Integration tests added/updated - N/A - [x] Manual testing performed - Verified UI builds successfully and no visual regressions - [ ] E2E tests added/updated - N/A ## Related Issues Closes #33941
5 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
This PR modernizes the dotcms-ui build configuration (moving to Nx’s esbuild executor) and replaces the legacy “starter” experience with a new role-based onboarding flow (Developer vs Marketer), including new onboarding components and supporting assets.
Changes:
- Migrates
dotcms-uibuild to@nx/angular:browser-esbuild, updates dev/prod build options, and adjusts serve behavior (HMR/live reload). - Refactors the starter portlet to a profile-selection UX and splits onboarding into new Developer/Author components; updates routing and removes the old starter module/resolver.
- Adds new onboarding-related logo assets and applies small UI/theme SCSS tweaks.
Reviewed changes
Copilot reviewed 30 out of 43 changed files in this pull request and generated 15 comments.
Show a summary per file
| File | Description |
|---|---|
| core-web/yarn.lock | Updates lockfile for ngx-markdown/Prism-related dependency graph. |
| core-web/package.json | Bumps ngx-markdown dependency range. |
| core-web/nx.json | Adjusts Nx target defaults for serve. |
| core-web/libs/dotcms-scss/angular/dotcms-theme/components/_tag.scss | Updates tag info background color token. |
| core-web/libs/dotcms-scss/angular/dotcms-theme/components/_overlaypanel.scss | Adds overlay panel border styling. |
| core-web/apps/dotcms-ui/src/tsconfig.spec.json | Removes unused/duplicate tsconfig under src/. |
| core-web/apps/dotcms-ui/src/tsconfig.app.json | Removes unused/duplicate tsconfig under src/. |
| core-web/apps/dotcms-ui/src/main.ts | Changes webcomponents bootstrapping behavior. |
| core-web/apps/dotcms-ui/src/assets/logos/sync.svg | Adds onboarding UI icon asset. |
| core-web/apps/dotcms-ui/src/assets/logos/reactjs.svg | Adds framework logo asset. |
| core-web/apps/dotcms-ui/src/assets/logos/php.png | Adds PHP logo asset. |
| core-web/apps/dotcms-ui/src/assets/logos/nextjs.svg | Adds Next.js logo asset. |
| core-web/apps/dotcms-ui/src/assets/logos/marketer.svg | Adds marketer role asset. |
| core-web/apps/dotcms-ui/src/assets/logos/external-link.svg | Adds external-link icon asset. |
| core-web/apps/dotcms-ui/src/assets/logos/dot-net.png | Adds .NET logo asset. |
| core-web/apps/dotcms-ui/src/assets/logos/copy.svg | Adds copy icon asset. |
| core-web/apps/dotcms-ui/src/assets/logos/code.svg | Adds developer role asset. |
| core-web/apps/dotcms-ui/src/assets/logos/check-circle.svg | Adds selection check icon asset. |
| core-web/apps/dotcms-ui/src/assets/logos/astro.svg | Adds Astro logo asset. |
| core-web/apps/dotcms-ui/src/app/view/components/main-legacy/main-legacy.component.scss | Refactors layout styling from flex to grid. |
| core-web/apps/dotcms-ui/src/app/view/components/main-legacy/main-legacy.component.html | Adjusts layout DOM structure to match grid layout. |
| core-web/apps/dotcms-ui/src/app/view/components/dot-navigation/components/dot-nav-item/dot-nav-item.component.scss | Tweaks nav item spacing/alignment. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter.routes.ts | Simplifies starter routes (removes resolver). |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter.module.ts | Removes legacy NgModule-based starter module. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter.component.ts | Implements role selection state + onboarding component composition. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter.component.spec.ts | Updates tests for role selection/onboarding display logic. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter.component.scss | Replaces starter styling with new role selection layout styles. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter.component.html | Replaces legacy starter UI with role selection + conditional onboarding. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter-resolver.service.ts | Removes legacy resolver logic. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/dot-starter-resolver.service.spec.ts | Removes resolver unit tests. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/components/onboarding-dev/onboarding-dev.component.ts | Adds developer onboarding component (framework list + actions). |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/components/onboarding-dev/onboarding-dev.component.spec.ts | Adds unit tests for dev onboarding rendering. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/components/onboarding-dev/onboarding-dev.component.scss | Adds styling for dev onboarding layout. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/components/onboarding-dev/onboarding-dev.component.html | Adds dev onboarding template with framework blocks. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/components/onboarding-dev/models.ts | Adds framework model for onboarding list. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/components/onboarding-author/onboarding-author.component.ts | Adds marketer/author onboarding component with permission-driven links. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/components/onboarding-author/onboarding-author.component.spec.ts | Adds unit tests for author onboarding permissions + actions. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/components/onboarding-author/onboarding-author.component.scss | Adds styling for author onboarding. |
| core-web/apps/dotcms-ui/src/app/portlets/dot-starter/components/onboarding-author/onboarding-author.component.html | Adds author onboarding template (ported/updated from legacy starter). |
| core-web/apps/dotcms-ui/src/app/portlets/dot-pages/dot-pages-store/dot-pages.store.spec.ts | Updates tests to use new mocks location and adjusts menu-action setup. |
| core-web/apps/dotcms-ui/src/app/app-routing.module.ts | Updates starter route to load route-array entry point; minor formatting tweak. |
| core-web/apps/dotcms-ui/project.json | Migrates build executor to browser-esbuild; updates build/serve options and adds scripts/styles. |
Comments suppressed due to low confidence (1)
core-web/apps/dotcms-ui/src/app/portlets/dot-pages/dot-pages-store/dot-pages.store.spec.ts:679
- In this test,
state$is subscribed without any unsubscription, anddone()can be called multiple times if the store emits again. Preferfilter(...)+take(1)(orfirstValueFrom) to make the assertion deterministic and avoid potential flakiness.
dotPageStore.state$.subscribe((data) => {
const menuActions = data.pages?.menuActions;
if (!menuActions || menuActions.length < 9) return;
expect(menuActions[7].label).toEqual('contenttypes.content.push_publish');
menuActions[7].command({ originalEvent: createFakeEvent('click') });
expect(dotPushPublishDialogService.open).toHaveBeenCalledWith({
assetIdentifier: item.identifier,
title: 'contenttypes.content.push_publish'
});
done();
});
Comment on lines
+22
to
+43
| @Component({ | ||
| selector: 'dot-onboarding-dev', | ||
| templateUrl: './onboarding-dev.component.html', | ||
| styleUrls: ['./onboarding-dev.component.scss'], | ||
| imports: [ | ||
| AccordionModule, | ||
| DotCopyButtonComponent, | ||
| ButtonModule, | ||
| CommonModule, | ||
| ButtonModule, | ||
| FormsModule, | ||
| KnobModule, | ||
| MarkdownModule, | ||
| OverlayPanelModule, | ||
| ProgressBarModule, | ||
| RadioButtonModule, | ||
| RouterModule, | ||
| TagModule, | ||
| TooltipModule, | ||
| TabViewModule | ||
| ] | ||
| }) |
There was a problem hiding this comment.
DotOnboardingDevComponent declares an imports array but is missing standalone: true. Angular only allows imports on standalone components, so this will fail compilation. Add standalone: true (or move these imports into a module).
Comment on lines
5
to
19
| @@ -15,4 +15,5 @@ if (environment.production) { | |||
| bootstrapApplication(AppComponent, { | |||
| providers: [importProvidersFrom(AppModule, BrowserAnimationsModule)] | |||
| }); | |||
| defineCustomElements(); | |||
|
|
|||
| // defineCustomElements(); | |||
There was a problem hiding this comment.
defineCustomElements() is commented out. The UI includes custom elements like <dotcms-template-builder-lib> (e.g. dot-edit-layout.component.html), which require webcomponents to be registered; leaving this disabled will break those views at runtime. Re-enable the import/call (or ensure registration happens elsewhere).
Comment on lines
63
to
+77
| "styles": [ | ||
| "node_modules/prismjs/themes/prism-okaidia.css", | ||
| "node_modules/primeicons/primeicons.css", | ||
| "libs/dotcms-scss/angular/styles.scss", | ||
| "node_modules/primeflex/primeflex.css", | ||
| "node_modules/primeng/resources/primeng.min.css", | ||
| "node_modules/gridstack/dist/gridstack.min.css" | ||
| ], | ||
| "scripts": [], | ||
| "scripts": [ | ||
| "node_modules/prismjs/prism.js", | ||
| "node_modules/prismjs/components/prism-css.min.js", | ||
| "node_modules/prismjs/components/prism-typescript.min.js", | ||
| "node_modules/prismjs/components/prism-bash.min.js", | ||
| "node_modules/clipboard/dist/clipboard.min.js" | ||
| ], |
There was a problem hiding this comment.
These global scripts/styles rely on prismjs and clipboard being present in node_modules, but they are not direct dependencies in core-web/package.json (currently only pulled transitively/optionally via ngx-markdown). Add them as explicit dependencies or avoid referencing them from the build config to prevent brittle builds.
Comment on lines
+3
to
+6
| data-testid="profile-selection" | ||
| style="height: 100%" | ||
| class="flex justify-content-center items-center flex-column main-container"> | ||
| <h1 class="text-center heading m-0">Welcome to dotCMS</h1> |
There was a problem hiding this comment.
items-center is not a PrimeFlex utility class (the rest of the app uses align-items-center). This likely won’t apply and will break vertical centering of the selection UI; switch to align-items-center.
| this.eventEmitter.emit('reset-user-profile'); | ||
| } | ||
| public openExternalLink(url: string): void { | ||
| window.open(url, '_blank'); |
There was a problem hiding this comment.
window.open(url, '_blank') enables reverse-tabnabbing via window.opener. Use noopener,noreferrer (e.g., third arg features) or an <a target="_blank" rel="noopener noreferrer"> pattern.
Suggested change
| window.open(url, '_blank'); | |
| window.open(url, '_blank', 'noopener,noreferrer'); |
Comment on lines
+33
to
+38
| <a | ||
| target="_blank" | ||
| style="text-decoration: none" | ||
| href="{{ framework.githubUrl }}"> | ||
| {{ framework.label }} starter kit | ||
| </a> |
There was a problem hiding this comment.
This external link uses target="_blank" without rel="noopener noreferrer", which allows reverse-tabnabbing. Add the rel attributes for security.
| icon="pi pi-refresh" | ||
| label="Not a developer?" | ||
| iconPos="left" | ||
| icon="pi pi-refresh" |
There was a problem hiding this comment.
The <p-button> has the icon attribute specified twice. Angular template compilation will reject duplicate attributes; remove one of them.
Suggested change
| icon="pi pi-refresh" |
Comment on lines
+14
to
+18
| <img | ||
| class="check-circle" | ||
| src="dotAdmin/assets/logos/check-circle.svg" | ||
| alt="check" /> | ||
| <img class="block mx-auto" src="dotAdmin/assets/logos/code.svg" alt="developer" /> |
There was a problem hiding this comment.
Asset paths here are relative (dotAdmin/...) while the new onboarding data uses absolute paths (/dotAdmin/...). Relative paths can break depending on baseHref/current route; use a consistent absolute /dotAdmin/... form for these logos.
Comment on lines
+29
to
+30
| <img class="check-circle" src="dotAdmin/assets/logos/check-circle.svg" /> | ||
| <img class="block mx-auto" src="dotAdmin/assets/logos/marketer.svg" /> |
There was a problem hiding this comment.
These images are missing alt text (and the check icon on the Marketer card has no alt at all), which is an accessibility issue. Add appropriate alt attributes (or alt="" if purely decorative).
Suggested change
| <img class="check-circle" src="dotAdmin/assets/logos/check-circle.svg" /> | |
| <img class="block mx-auto" src="dotAdmin/assets/logos/marketer.svg" /> | |
| <img class="check-circle" src="dotAdmin/assets/logos/check-circle.svg" alt="check" /> | |
| <img class="block mx-auto" src="dotAdmin/assets/logos/marketer.svg" alt="marketer" /> |
| /** | ||
| * Hit the endpoint to show/hide the tool group in the menu. | ||
| * @param {boolean} hide | ||
| * @memberof DotStarterComponent |
There was a problem hiding this comment.
The JSDoc here still references @memberof DotStarterComponent, but the method now lives in DotOnboardingAuthorComponent. Update/remove the stale tag to avoid misleading documentation.
Suggested change
| * @memberof DotStarterComponent | |
| * @memberof DotOnboardingAuthorComponent |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces significant improvements to the build configuration and onboarding experience in the
dotcms-uiAngular application. The most notable changes include migrating the build process to use Nx's esbuild executor, updating build and serve options for better performance and development workflow, and delivering a comprehensive redesign of the onboarding author component with dynamic user-driven content and resource links.Build System and Configuration Updates:
@angular-devkit/build-angular:applicationto@nx/angular:browser-esbuildfor improved build speed and modern tooling, and updated related build options such asoutputPath,main, andpolyfillsinproject.json.vendorChunk,buildOptimizer,namedChunks, and fine-tuned production/development settings for performance and debugging. [1] [2] [3]servetarget to use Hot Module Replacement (hmr), disabled live reload, and cleaned up configuration options for a smoother local development experience.Onboarding Experience Improvements:
onboarding-author.component.htmlto provide a dynamic onboarding interface based on user data, featuring actionable links for creating content, templates, and pages, as well as quick access to documentation, training, and community resources.Routing Update:
dot-starter.routesentry point, enabling more modular and maintainable routing.Untitled.Project18.mp4