Upgrade JSS 22.x Angular apps to Content SDK 1.0

What's new in Content SDK for Angular 1.0?

Content SDK for Angular consolidates the JSS Angular packages into a single @sitecore-content-sdk/angular package and modernizes the app architecture using the latest Angular features, such as standalone components, signals, and route resolvers:

• Standalone, no NgModule usage - boots through bootstrapApplication with an ApplicationConfig (app.config.ts) instead of AppModule/AppServerModule. Components are standalone and declare their own imports.
• Route resolvers (known as loaders) - data fetching moves out of JssContextService and into loader functions. These are Angular route resolvers registered with provideLoaderRegistry() and wired into routes with loaderResolver(). The same loaders run on the server (initial render) and the client (subsequent navigations, via a /_data endpoint).
• SitecoreClient - A single client object exposes getPage, getPreview, getErrorPage, getDictiona ry, and getHeadLinks. It replaces the JSS GraphQLLayoutService / GraphQLDictionaryService factories.
• Server middleware - multisite, personalization, bot tracking, and SXA redirects all run as Express middleware on the SSR host (server.ts) rather than as client-side components. Editing, experimental features, cache admin, revalidation, and the loader-data endpoint are also middleware. The host exports its Node request handler as the module's default export, in addition to the existing reqHandler named export.
• Signals-based context - SitecoreContextService exposes the current page() and helpers like isEditing() as signals, replacing the RxJS state observable on JssContextService.
• sitecore-tools CLI - sitecore.config.ts and sitecore.cli.config.ts drive configuration, the generated component map, sites.json, and metadata.json under .sitecore/.

Create a new Content SDK application

You can scaffold the new app with the latest version of the create-content-sdk-app package:

1. Run the following command:

   npx create-content-sdk-app@latest

2. When prompted to choose a template, choose angular.

3. Install dependencies and confirm the app runs before migrating anything:

   
   npm install
   npm run dev
   

The generator creates a complete, runnable Content SDK for Angular app with the following:

• Standalone bootstrap (app.config.ts / app.config.server.ts).
• Routing with locale matching, loaders, and 404/500 error routes (app.routes.ts / app.routes.server.ts).
• A SitecoreClient and out-of-the-box loaders under src/content-sdk/.
• An Express SSR host (server.ts) with multisite, personalization, bot tracking, SXA redirects, editing, cache, and loader-data middleware already wired.
• sitecore.config.ts/sitecore.cli.config.ts and the .sitecore/ generated files (component map, sites.json, metadata.json).
• A set of out-of-the-box components (Image, Promo, RichText, Navigation, and so on).

Configure your environment

Content SDK centralizes configuration in the sitecore.config.ts file, splits client and server values, and generates environment files. Environment variables change name and shape from the JSS environment.js/JssConfig.

Client-exposed values use the CSDK_PUBLIC_ prefix and are baked into src/environments/environment.ts by npm run gen:env:dev/gen:env:prod. Server-only values are read from process.env, loaded by src/load-env.ts. Create a copy of the .env.example file, rename it to .env, and fill in the appropriate values from SitecoreAI:

The following factories you used in JSS to build services from these values have no equivalent.

• graphql-client-factory
• layout-service-factory
• dictionary-service-factory
• src/app/lib/config.ts

Migrate your components

In JSS, components were declared in an auto-generated AppComponentsModule through JssModule.withComponents([...]). They used an @Input() rendering, templateUrl / *.html files, and standalone: false. The shared SxaComponent base class read rendering.params.

In Content SDK, components are standalone, declare their own imports, and are discovered by the sitecore-tools CLI into a generated .sitecore/component-map.ts.

The following example shows how new Angular practices can be applied to components:

@Component({
  selector: 'app-content-block',
  imports: [ScTextDirective, ScRichTextDirective],
  template: `
    <div class="contentBlock">
      <h2 class="contentTitle" *scText="headingField()"></h2>
      <div class="contentDescription">
        @if (contentField(); as content) {
          <div *scRichText="content"></div>
        }
      </div>
    </div>
  `,
})
export class ContentBlockComponent extends SxaComponent {
  readonly headingField = computed(() => /* ... */);
  readonly contentField = computed(() => /* ... */);
}
export default ContentBlockComponent;

The key component differences stem from both Angular and Content SDK changes:

• Base class - new SxaComponent uses signal inputs and exposes fields(), params(), rendering(), renderingId(), and styles() as signals/computeds:

  export abstract class SxaComponent {
    readonly fields = input<Record<string, unknown>>();
    readonly params = input<Record<string, string>>();
    readonly rendering = input<ComponentRendering>();
    readonly renderingId = computedRenderingId(() => this.params());
    readonly styles = computed(() => this.params()?.Styles?.trim() ?? '');
  }

  Components receive fields/params as bound inputs from the placeholder, not a single rendering object.

• Directives - *scText, *scRichText, *scImage, *scLink, and <sc-placeholder> come from @sitecore-content-sdk/angular and must be added to each component's imports array as they are no longer globally available through JssModule.

• Variants - JSS selected template variants with @ViewChild/TemplateRef and rendering.params.FieldNames. Content SDK exports a named class per variant and lets the component map resolve them. For example:

  export { ImageDefaultComponent as Default, ImageBannerComponent as Banner };

• Host bindings -SXA host classes and IDs move to the host ({ '[attr.class]': "...", '[attr.id]': 'renderingId()' }) and use signals (styles(), renderingId()).

• Editing checks - replaces JssContextService.state.subscribe(... context.pageEditing ...) with inject(SitecoreContextService).isEditing(). See Read context data from SitecoreContextService for more information.

The auto-generated AppComponentsModule is replaced by .sitecore/component-map.ts, which sitecore-tools generates from the components under src/app/components. After adding or moving a component, regenerate the map with the following command:

npm run sitecore-tools:generate-map

The map is provided through SITECORE_COMPONENT_MAP in app.config.ts and passed to the editing config middleware in server.ts, both of which are already wired in the generated app.

Read context data

If your JSS components or services read from Sitecore context, you must migrate those reads. JSS exposed context as an RxJS observable (JssContextService.state) built on JssStateService<JssState>, plus a custom JssState class. Components subscribed to it and had to unsubscribe in ngOnDestroy.

Content SDK exposes context as signals through SitecoreContextService. There is no JssState, no changeRoute, and no manual subscription management. Derive view state with computed() and side effects with effect() instead of subscribing.

For example, the JSS image component subscribed to context to compute an editing flag:

// JSS
this.contextSubscription = this.jssContext.state.subscribe((s) => {
  this.isEditing = s.sitecore && s.sitecore.context.pageEditing;
});

The Content SDK equivalent reads the signal directly inside a computed(), with no subscription to clean up:

// Content SDK
private readonly context = inject(SitecoreContextService);
readonly wrapWithLink = computed(() => !this.context.isEditing() && !!this.href()?.trim());

Language switching likewise moves from an RxJS subscription in AppComponent to an effect() in the root component that reads context.page()?.locale.

Fetch data with SitecoreClient and loaders

If you fetched layout, dictionary, or other Sitecore data directly (through JssLayoutService, JssContextService.changeRoute, or the GraphQL service factories), migrate that logic to SitecoreClient.

For one-off, non-route data fetches, you can call the getClient() method on getPage, getDictionary, getErrorPage, or getHeadLinks) directly:

import { getClient } from '../client/sitecore-client';
...
const scClient = getClient();
scClient.getPage(...) // get layout data for a specific page

Migrate existing internationalization implementation

JSS wired @ngx-translate to a custom JssTranslationLoaderService/JssTranslationClientLoaderService pair that called a GraphQLDictionaryService (created by dictionary-service-factory) and used TransferState to pass server data to the client. AppComponent switched languages by subscribing to JssContextService.state.

The new app provides translation out of the box through SitecoreTranslateLoader (registered in app.config.ts) and a dictionary route loader that calls getClient().getDictionary(...), keyed by the resolved site and locale. Language switching uses the signal-based effect described in Read context data.

Delete src/app/i18n/* and dictionary-service-factory.ts from your old code. Do not port them. If you used dictionary phrases in components, the lookup API (@ngx-translate translate pipe/service) is unchanged.

Obsolete and revised functionality

Some parts of existing JSS apps are either revised or no longer required in Content SDK apps, meaning they can be removed. However, if your app contains custom code that uses any of this obsolete functionality, or if you have any customizations in the affected files or folders, you will need to modify your app accordingly.

Optional steps

The following steps apply only if you customized personalization, multisite, or other middleware in the proxy companion application in JSS. Otherwise, you can skip this section.

const middlewareMatcher = {
  excludePaths: ['/healthz', '/metrics', /\.[^/]+$/],
  // includePaths: [/^\/[a-z]{2}(-[A-Z]{2})?(\/|$)/], // restrict to locale-prefixed routes
};

Next steps

To finalize the upgrade process, make sure you resolve any errors and warnings you encounter. Use the following items as a checklist to verify all the functionality:

• Bring your components across one at a time. Convert each component to standalone with signal inputs, add the required *sc* directives to imports, and run npm run sitecore-tools:generate-map so it appears in the .sitecore/component-map.ts file.
• Run npm run dev and verify routing, locale prefixes, dictionary phrases, and editing in Sitecore Pages (metadata mode).
• Configure your sites and verify multisite resolution against .sitecore/sites.json.
• Configure Edge (context ID/client context ID) and verify personalization and CDP page-view events in a deployed environment as these do not run against local containers.
• Review the Loaders cache layer and tags revalidation topic. Consider using hooks and the POST /api/revalidate endpoint for your hosting environment.