Your Sitecore Dictionary Items are Returning as an Empty Array
I was recently working on a project where we were using Sitecore Dictionary Items as labels for items returned by our API Driven Middle Layer. This is beneficial since we can connect product codes, account types, and system IDs directly to editable items in Sitecore. One of the other developers on the project was creating and hooking up the Dictionary Items to our Headless Next.js frontend; however, once I serialized the changes - I could see the items in Sitecore, but they weren't loading on my local machine's frontend. To top it off, it was working on our Vercel frontend, so I knew it was a configuration issue on my local machine.
I'm going to walk through the steps I took to debug this problem, how I solved it, and what the solution was. So if you're also having a similar issue, you can use my debugging steps to hopefully highlight the issues in your own project.
Project Specifications:
- Sitecore 10.3 with SXA (Multi-site, No Docker)
- Sitecore TDS for Serialization
- Sitecore Next.js JSS 22.5.1
Debugging the Sitecore Dictionary Item
1. Are We Getting a Response on the FE from Sitecore
Since we were running a headless site with a next.js frontend, my first goal was to see if the data is even being sent to my local frontend. So my first step was opening up my _app.tsx and inspect what was being provided by the SitecorePageProps and console logging it to the frontend. This will also allow me to double-check that the I18nProvider **is correctly configured and set up.
The response I got from the console.log was an empty array. This proved that the issue was with the connection to Sitecore and not an issue specifically in my frontend with displaying the items.
2. Testing the Layout Service Using Sitecore GraphQL Playground
My next step was validating the Layout Services response from Sitecore by going to the GraphQL playground. To do this, I went to the JSS GitHub to look for the GraphQL specific query that returns the dictionary items - specifically, the graphql-dictionary-service.ts file. Inside this file, you can immediately see the GraphQL query that you need to copy on line 17.
Once I had the query, I opened up the Sitecore GraphQL Playground and tested to see the response. As I suspected, the value returned was also an empty array. This means that the Layout Service is unable to find any Dictionary Items to send to the frontend.
Sitecore GraphQL Playground URL: https://{LocalHostBaseUrl}/sitecore/api/graph/edge/ui?sc_apikey={YourSitecoreApiKey}
Full GraphQL Query from the JSS GitHub:
/** @default */
const query = /* GraphQL */ `
query DictionarySearch(
$rootItemId: String!
$language: String!
$templates: String!
$pageSize: Int = 10
$after: String
) {
search(
where: {
AND: [
{ name: "_path", value: $rootItemId, operator: CONTAINS }
{ name: "_language", value: $language }
{ name: "_templates", value: $templates, operator: CONTAINS }
]
}
first: $pageSize
after: $after
) {
total
pageInfo {
endCursor
hasNext
}
results {
key: field(name: "Key") {
value
}
phrase: field(name: "Phrase") {
value
}
}
}
}
`;
3. Checking the Dictionary Configurations in Sitecore
The first step in ensuring that the basic configuration is correct is checking the Dictionary Domain & Path values in the site settings. This value should be pointing to your dictionary Item. To find the values, you want to click directly on the Settings item in your Sitecore tree and scroll down until you find Dictionary Path & Dictionary Domain.
Since my domain configurations were correct, the next thing I wanted to look at were the dictionary items themselves. I thought that perhaps the items had errors. To check this, you can right-click on the gutter. In case you're unaware, the Sitecore gutter is the small bar along the left side of the screen that sits just behind the object explorer. Once I right-clicked on the gutter, I enabled Workflow, Missing Versions and Publishing Warnings to see if anything was getting flagged; however, in my case everything seemed fine.
The final thing I tried in Sitecore before looking back at my Next.js configuration was republishing the dictionary items. Now your local instance should be configured to pull all its information from the Master database, not the Web database - but I thought it wouldn't hurt to start the publishing in the background while I was checking other things.
If you are having issues on a deployed instance of Sitecore, then ensuring you republish the entire dictionary folder is a great idea.
4. Double-checking the Frontend Dictionary Configuration
There are a few basic items in your Next.js solution that you should check when you're having issues with your dictionary items. The first of which is ensuring that you have a matching appName in your package.json. While having an app name that doesn't match Sitecore should cause a plethora of other problems on your front end, it's always a good idea to double-check in case it was updated by someone else on your project.
Since my appName matched in Sitecore, the next step was double-checking the root item ID inside the dictionary-service-factory.ts. This ID is what connects the data items in the frontend to the dictionary item in Sitecore. Depending on your version of Sitecore the ID value might point to the site itself or to the actual dictionary item. In XM Cloud and SXA sites, this value isn't actually needed, since Sitecore will search the solution automatically and auto resolve the item. However, since I was working with an 10.3 Sitecore instance that had SXA installed on it after the fact, I needed to keep the root ID pointing directly to the dictionary item.
The main takeaway here is to double-check if the ID is pointing to the correct location, and if you're on a fresh SXA install or using XM Cloud, try removing the value altogether to see if that will fix your problem.
My final step in double-checking the configuration was looking at the auto generated config.js file and the corresponding ENV variables to make sure that the values were correct. You can find this file in src/temp/config.js. The main goal was to look for inconsistencies and to see if anything stood out as incorrect. Ex: Checking the Site Name to see if it matched.
5. Try Reindexing the Databases
The Layout Service's GraphQL query can fetch using a solar site or search query. The basic query is default for non XM cloud sites, since my instance was Sitecore 10.3 with SXA installed after the fact, I was confident that we were using a basic query to look for the items. It was at this point that I thought about re-indexing the database, since I was unable to find the items in the GraphQL Playground.
If you look at the GitHub for the JSS graphql-dictionary-service.ts file again and scroll to line 176, you can see the search query that's used to pull dictionary items on non XM Cloud sites. It was looking at this query that made me realize that re-indexing the databases might fix the issue.
To rebuild your databases, go to the Control Panel and click on “Index Manager” in the bottom left. Once you have the Index Manager open, you can rebuild your databases. I only wanted to rebuild the master and web indexes, so I didn't run the core re-index.
This fixed the issue! Once the index had been recreated, I was able to see my dictionary items on the frontend once I refreshed the page.
Issue Solved, but Why did it Happen?
Reindexing the database solved my issue, but why was this a problem to begin with? Well, using Sitecore TDS/Source Control to serialize your items to Sitecore doesn't automatically add items to the index. This wasn't an issue on our Server environment since the server has auto indexing which indexes the databases daily and our primary CICD pipeline start an index when it finished running (This is also a default XM Cloud post action - all search indexes are refreshed after every deploy).
Hopefully you can use my mistake and subsequent lesson to fix an issue of your own, or at the very least learned more about how you can debug Sitecore issues.
