Kontent.ai multi-web sample application template

Demo

Ficto Healthtech

Ficto Imaging

Ficto Surgical

Getting Started

To run the app yourself you will need a clone of the Kontent.ai project. You can create it right from the Kontent.ai UI as a multi-brand sample project. You can learn more about the sample project in our documentation.

Deploy

Init project from command line

Execute create-next-app with npm or Yarn to bootstrap the example:

npx create-next-app --example https://github.com/kontent-ai/sample-app-next-js sample-app-next-js
# or
yarn create next-app --example https://github.com/kontent-ai/sample-app-next-js sample-app-next-js

Preview mode

The app uses the Next's preview mode to display Kontent.ai preview data on the site.

All the features, including preview urls, Web Spotlight and multiple previews are configured automatically when the project is generated. Next.js preview mode is also toggled whenever you view content via Web Spotlight or Preview button.

If you open the app outside of Kontent.ai, it will by default show the published content. To enable the preview mode, visit the /api/preview route and provide the following query parameters:

• secret - This prevents unauthorised access to the preview data. Default value is mySuperSecret.
• slug - This defines where should the app redirect you once the preview mode is enabled (e.g. /).
• type - This must be the codename of the content type that the item represented by slug is based on. It can be either page or web_spotlight_root.

An example might look something like this: /api/preview?secret=mySuperSecret&slug=about-us&type=page. To exit the preview mode, visit the route /api/exit-preview. No query parameter is necessary, but you can provide callback with a path to redirect to once the preview mode is disabled.

The preview mode leverages cookies, so when you open the app in preview (e.g. from Kontent.ai) and then open it again (e.g. in a different tab), the second instance will remain in preview, as long as the cookies are present. You can clear cookies manually or visit /api/exit-preview which removes them as well.

Code development

Environment variables

1. Set up environment variables

   • Copy the .env.local.template file in this directory to .env.local (which will be ignored by Git):

     cp .env.local.template .env.local

   • Fill in all the necessary variables in .env.local based on the comments.

2. Run the development server:

   npm run dev
   # or
   yarn dev

🎉 Open http://localhost:3000 with your browser to see the result.

Running the app in web spotlight

If you want to use your app inside web spotlight, you will need to run the app under the https scheme.

To run the app under the https scheme you can use one of the following methods:

• Run npm run https:dev to run the app in the development mode and a proxy server proxying https://localhost:3001 to http://localhost:3000.
  • The proxy will use a self-signed certificate which might not work in some browsers.
  • The proxy is run using the local-ssl-proxy package.
  • The command requires the ports 3001 and 3000 to be free, otherwise it fails. If you want to use different ports, you will need to run the proxy (npm run https:proxy) and the app npm run dev yourself.
• Run npm run https:proxy to create a proxy as above without running the app (you are expected to run the app separately).
  • You can use this command with a custom trusted certificate like this npm run https:proxy -- --key localhost-key.pem --cert localhost.pem. See the package documentation for more details
  • You can also change the source and/or target port (e.g. npm run https:proxy -- --source 3002 --target 4000)
• Write your own server.
• Use Ngrok or a similar tool.

You can adjust the homepage by editing pages/[envId]/index.tsx. The page auto-updates as you edit the file.

To generate new models from Kontent.ai data, just run npm run generateModels. Make sure you have environment variables filled in properly.

Circular reference handling

Next.js data fetching functions convert objects to JSON format. Since JSON doesn't support circular data, this can potentially cause crashes in situations where objects reference each other, such as with linked items or rich text elements. To avoid this, the application uses the flatted package to implement two helper functions: stringifyAsType and parseFlatted, which allow for safe conversion of circular structures into a string form in getStaticProps and then accurately reconstruct the original objects from that string.

Use codebase as a starter

⚠ This project is not intended as a starter project. It is a sample of a presentation channel showcasing Kontent.ai capabilities. The following hints help you use this code as a base for presentation channel for your project like a boilerplate. By doing it, you are accepting the fact you are changing the purpose of this code.

The app contains code to dynamically handle different Kontent.ai projects (e.g. the environment route prefix). To adjust the code to be used for a single project as a starter, you should remove the logic that is used solely for showcasing the sample project during evaluation.

Below are some of the parts responsible for handling different Kontent.ai projects that need adjustment in case of transforming the code into a single-project setup:

• middleware.ts - Gets the Kontent.ai environment ID and stores it in a cookie. For single-project setup, a single environment variable should be used to store the environment ID.
• pages/callback.tsx & pages/getPreviewApiKey.ts & lib/constants/auth.ts - Responsible for exchanging preview API keys for specified environment. For single-project setup, a single environment variable should be used to store the preview API key.
• pages/[envId] - Folder representing the dynamic segment, passing the environment ID for pages. For single-project setup, remove the folder and move its content one level up.

Commands

sample-app-next-js/package.json

Lines 4 to 15 in 001994b

	"scripts": {
	"generateModels": "tsc --project scripts/tsconfig.json && node scripts/build/generateModels.mjs",
	"dev": "next dev",
	"lint": "next lint",
	"lint:fix": "next lint --fix",
	"build": "next build",
	"export": "next export",
	"start": "next start",
	"test": "jest"
	},
	"dependencies": {
	"@heroicons/react": "^2.0.17",