You can follow the steps for JSS to content-sdk upgrade using many guides online, but later when you try to test your site locally or when deploying to Netlify/Vercel etc., you will face many hindrances. My guide here was prepared to help you, so you can skip those issues and proceed with a full deployment and testing.
Step 1. Download the latest vanilla content-sdk using “npx create-content-sdk-app@latest nextjs”. Let this be the source.
Step 2. Create a branch out of existing JSS sdk application repository, that needs to be upgraded and let that be the target for upgrade.
Step 3. Upgrade the “package.json” file in target, merging content from “Package.json” file from source, by upgrading the versions for dependencies compatible for the application.
Step 4. Make sure to merge the "scripts" section as well, to make sure latest from “package.json” file from source are maintained.
Step 5. Clean up the “package.json” file of legacy config, keeping only essential locales. For instance, it will be like:
"config": {
"locales": [
"en"
]
}
Step 6. Update the scripts in “package.json” file so it has these:
"build": "cross-env NODE_ENV=production npm-run-all --serial bootstrap ensure-sitecore-dir sitecore-tools:generate-map generate-sitecore-files next:build",
"ensure-sitecore-dir": "ts-node scripts/ensure-sitecore-dir.ts",
"generate-sitecore-files": "ts-node scripts/generate-sitecore-files.ts",
Step 7. Within the target “scripts” folder, add a file “ensure-sitecore-dir.ts” with content:
Step 8. Within the target folder “scripts”, add a file “generate-sitecore-files.ts”. It should contain your site information. For instance, for XMC accelerator DEV we have the following:
// eslint-disable-next-line @typescript-eslint/no-require-imports
const { existsSync: fileExists, writeFileSync: writeFile } = require('fs')
// eslint-disable-next-line @typescript-eslint/no-require-imports
const { join: pathJoin } = require('path')
const sitecorePath = pathJoin(process.cwd(), '.sitecore')
// Generate metadata.json
const metadata = {
version: '1.0.0',
generated: new Date().toISOString(),
components: [],
}
// Generate sites.json
const sites = {
defaultSite: process.env.NEXT_PUBLIC_DEFAULT_SITE_NAME || 'xcentium',
sites: [
{
name: 'Default',
host: 'localhost',
language: 'en',
},
{
name: '[YOUR SITE NAME]',
host:’[YOUR DEPLOYED SITE URL (NETLIFY/VERCEL)]’,
language: 'en',
},
… OTHER SITES IF ANY
],
}
// Generate import-map.ts
const importMap = `// Auto-generated import map for Sitecore components
export const componentMap = {
// Component mappings will be populated by generate-map
}
export default componentMap`
// Write files
if (!fileExists(pathJoin(sitecorePath, 'metadata.json'))) {
console.log('Creating metadata.json...')
writeFile(pathJoin(sitecorePath, 'metadata.json'), JSON.stringify(metadata, null, 2))
}
if (!fileExists(pathJoin(sitecorePath, 'sites.json'))) {
console.log('Creating sites.json...')
writeFile(pathJoin(sitecorePath, 'sites.json'), JSON.stringify(sites, null, 2))
}
if (!fileExists(pathJoin(sitecorePath, 'import-map.ts'))) {
console.log('Creating import-map.ts...')
writeFile(pathJoin(sitecorePath, 'import-map.ts'), importMap)
}
console.log('Sitecore files generated successfully')
Step 9. In the “.env” file at target, make sure you have content-sdk specific entries like:
SITECORE_EDGE_CONTEXT_ID
NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID
NEXT_PUBLIC_DEFAULT_SITE_NAME
SITECORE_EDITING_SECRET
Step 10. Merge the contents of “next.config.js” from “source” to “target”. Make sure you have this entry within “const nextConfig = {”:
// Fix Next.js workspace root detection for Design Studio
outputFileTracingRoot: process.cwd(),
Step 11. The _app.tsx file must have references to all CSS files used in the application, by importing all the CSS files directly at the top level. For example:
import 'src/assets/main.coveo.css'
import 'src/assets/main.default.css' etc.
Step 12. Add a “Bootstrap.ts” file to target “scripts” folder, that should be something like this:
Step 13. Update the file in target “sitecore.config.ts” with:
Step 14. In the target [[..path]].tsx, 404.tsx, 500.tsx, and Layout.tsx, remove all usages of headLinks. and make sure you have this code along with anything else:
Step 15. Merge contents from source “tsconfig.json” with target “tsconfig.json”.
Step 16. In the target file “\src\pages\api\editing\config.ts”, add the following before instantiating ”EditingConfigMiddleware”:
Step 17. In the target file “\src\pages\api\robots.ts”, add the following before instantiating “RobotsMiddleware”:
Step 18. In the target file “src\pages\api\sitemap.ts”, add the following before instantiating “SitemapMiddleware”:
Step 19. If any standalone modules with its own “package.json” exists in Source, make sure you upgrade the “package.json” with content-sdk compatible module versions and copy them over to target. Such modules along with its files, except for the main component files (as configured under Sitecore/renderings), should be moved outside of “/src/components” folder.
Step 20. You might have to disable some strict rules like for instance, for usage of “any”, in the file “upgrade\eslint.config.mjs”
Step 21. Now you can traverse through all your component files in target (“/src/components”) and upgrade them to use content-sdk.
Step 22. CSS file references must be used directly in referring component inline. The components should use inline Tailwind CSS classes instead of the CSS module, making it more maintainable and eliminating the need for the separate CSS file. Please take windsurf help for this task, for each component referring the CSS file from the component folder.
Step 23. Since all the referred files by a component is now in-lined inside this component, if this is the only main component file in that component folder, then you can delete other files, earlier referred to by this file, from that folder now. Please note that the component folders might contain more than one main component file with its own references/variants and in that case, you should not delete anything from the component folder until you are done upgrading all main components in that folder.
Step 24. Please note that content-SDK uses the exact same case for rendering parameter fields and datasource fields as defined in Sitecore. Meaning, if there are Sitecore fields named as “Name”, “Title” etc., the route “fields” in the component should use the same case of “Name”, “Title” and not “name”/”title” etc. This is a very important change from JSS sdk to content sdk.
Step 25. The variant wrappers must be within the variant itself, meaning, if the earlier main component function rendering the variant, had a wrapper for the variant, the wrapper should be within each variant function as well, as content-SDK directly renders the variant. Example, if the main component function has:
<div
className={`component ${props?.params?.styles ?? ''} ${props.params?.GridParameters ?? ''} ${variantName}`}
id={id ? id : undefined}
>
{variant(props)}
</div>
the variant function should also render this same wrapper div:
<div
className={`component ${props?.params?.styles ?? ''} ${props.params?.GridParameters ?? ''} ${variantName}`}
id={id ? id : undefined}
>
{variant html}
</div>
Step 26. If there were build errors that remained to be solved earlier, you can work on them now. You can refer to https://doc.sitecore.com/sai/en/developers/content-sdk/upgrade-jss-22-8-next-js-apps-to-content-sdk-1-0.html and also the windsurf rules under the content-sdk vanilla instance you downloaded (“\nextjs\.windsurfrules”), to make sure you have not missed on any.
Step 27. You can check on other lib/utility files to make sure they are using content-sdk.
Step 28. You can delete any of the files that are not used any more. Always, compare with files in the content-sdk vanilla instance, if any doubts. Content-SDK solutions are very light weight and hence there are many files you can delete from earlier JSS SDK.
Step 29. Try build and run, this now completely upgraded target project solution (Step# 2), and test the pages.
Conclusion:
After having followed all these steps, I hope you are all set with your Content-sdk upgraded site. You should be able to test locally and also deploy to your rendering host (Netlify/Vercel etc.).