Installing Compose in an existing space
Why is work required at all?
You can use Compose to manage your already existing content. This is achieved by making changes to your existing content model and entries.
Compose has several specific content model requirements, which will need to be adapted by your development team in order to use Compose for your content team.
Since there is a variety of content models that can be created in the Contentful web app, we can’t guarantee that every content model can be adapted to be used with Compose. However, the best practices laid out in this article should make the process smooth for the vast majority of Contentful customers.
Please use the recommendations and instructions below to adapt your content model to further manage your existing content in Compose.
Overview of steps
To be able to use Compose for an existing space and website, you need to plan for four major steps:
Migration planning: Make a plan for your migration, allocate resources and inform your team and stakeholders.
Content model migration: All the changes that are needed to make your existing space compatible with the Compose content model requirements.
Code changes to your website: All the changes that are required to the code of your website to make API calls to load and render web pages based on the Compose content model.
Bring your changes live: In a coordinated step you will apply the new content model to the production environment and deploy the updated code.
Step 1: Migration planning
Analyzing your space and planning team work
Before you start your migration, it is recommended to make a plan of all the necessary steps and details that you need to consider:
- Take inventory of your current space:
- How many web pages exist? (Tip: if you have a sitemap.xml then this is a great resource)
- What are the most important pages? (Tip: use your analytics software)
- What links exist between pages?
- How many page types are used?
- How many pages exist for each page type: if the number is very low, a manual recreation of the page in Compose might be faster than a scripted migration.
- What are the patterns to construct URLs for pages?
- How are URLs structured for each page type?
- Check if your space and workflow relies on Apps or UI Extensions that are not supported by Compose.
- Make a plan to train your editorial team on how to use Compose.
- Request developer support and get estimates on the effort.
- Ensure that your space has enough remaining content types as per your subscription plan: Compose requires two content types that are Compose-specific and at least one for each page type.
- Align migration plan and timeline with your editorial team and other stakeholders.
Tip: Before doing a migration, it is a good time to do some housekeeping and retire low performing or outdated pages with the advantage of having less content to migrate.
Evaluating the content model changes needed
By evaluating your existing content model in relation to the Compose content model, you can see how much content model adaptation work will be required to support Compose in your space. Models that have a lot of overlap with Compose should be fairly straightforward, while those that diverge heavily will require more planning and work. Go through the questions listed below in bold to compare your existing content model against the Compose content model.
Does your content model use the concept of “pages”?
Yes; pages are explicit and managed via assemblies. The content model includes page-like terms (e.g., Recipe Page, Product Page, Author Page). Compose uses this model, so migrating should be straightforward. Usually the case when:
- Content type names or IDs contain “page, article, post” or similar page-like strings.
- Content type has a slug field and other page metadata (such as SEO fields).
No; pages are implied. Topic content types are used as pages (e.g., Recipe, Products, Authors). Compose does not use this pattern, so you’ll need to create a page type for each topic content type that is also represented as a page. Usually the case when:
- No content type name or ID contains “page, article, post” or similar page-like strings.
- Content type has a slug field and other page metadata (such as SEO fields).
- Website has specific routes for each topic (e.g. website.com /recipe/
Mixed; some pages are explicit, and others are implied. Compose defines pages explicitly, so you’ll need to define each page in your content model explicitly as well. Usually the case when:
- Mostly topic content types that are used as pages (see above).
- One or two content types for static or generic pages (such as imprint or terms of service).
How many top-level page types are used?
- One top-level page type. Compose uses this model, so migrating should be straightforward.
- Multiple top-level page types. Compose defines a single top-level page type, and allows you to define multiple page types based on that top-level page type (e.g., Article, Blog Post)
How are page URLs managed?
- URLs are defined via slug fields. Compose uses this pattern, so migrating should be straightforward.
- URLs are defined via reference fields. Compose doesn’t support this pattern; you’ll need to migrate URLs into slug fields.
- Pages are referenced via slug content types. Compose doesn’t support this pattern; you’ll need to migrate URLs into slug fields.
How is existing page metadata defined?
The Compose content model has some predefined page metadata fields. It is also very likely that your page content types will have similar – yet different – fields (such as title, SEO metadata or layout settings). Inspect your content model and make a plan for migrating these fields:
- What existing metadata fields can be mapped to the predefined fields of Compose? Typical fields: Page title, internal page name, SEO metadata
- Which custom fields should be added and migrated to the “Compose: Page” or “Compose: SEO” content type?
- Should custom page metadata fields apply to all pages? If yes, then extend the “Compose: Page” or “Compose: SEO” content types. Otherwise consider adding the field to one or more page types.
How is page content defined?
Compose encapsulates the content of a page inside an entry that is based on one of the custom defined page types (see diagram below).
Depending on the way page content is defined in your current content model, you might need to make adjustments to be compatible with Compose. Usually this means you need to make a distinction between page metadata and page content. Fields that represent page content must be migrated to one or more page types so that they can be used in Compose.
Below are some common patterns for managing page content and how to migrate them to Compose:
- Content is defined via page type entries on a single reference field. Compose uses this pattern; see the “Content” reference field in the diagram below. Little or no migration is needed. You can reuse your existing content type as a page type by adding it to Compose.
- Single Rich Text field (with embedded entries). Compose doesn’t use this pattern; you’d need to migrate your Rich Text field and its content to a page type.
- Content blocks via a multi-reference field. Compose doesn’t use this pattern; you’d need to migrate your reference field and its links to a page type
- Multiple fields on the page. Compose doesn’t use this pattern; you need to migrate your fields to a page type.
- Mixed; a combination of the above patterns. Compose requires an extra layer of abstraction between the “Compose: Page” and each “
” (named however you want). Each content field just needs to be parented to the page type.
Key points before you begin
- Compose installation is a major event, so to ensure that you don’t experience any disruption, it’s important to follow the instructions to back up your existing pages.
- Installing Compose into an existing space and adjusting the content model to a compatible format requires migration scripts using a CMS as Code approach. We advise that your developer team reads the documentation of our Command Line Interface (CLI) to get familiar with exporting content (to create a local backup) as well as writing and executing migration scripts. It’s very likely that you will need to repeat the migration process multiple times as you work through issues, and scripting the migrations will codify all the required steps in a repeatable way. This is especially useful if your production content changes while you are preparing the migration or if you make mistakes and have to start over from a fresh environment copy.
- Set up the CLI for use with Compose: The Compose-compatible CLI ensures that Compose specific settings can be managed with our developer tooling.
Step 2: Content model migration to Compose
Create dedicated environment
We strongly recommend that you perform the Compose migration in a dedicated space environment to ensure that your production content is not affected in case anything goes wrong.
Back up your content
Create a backup copy of your content to ensure that you are playing it safe. If anything goes wrong you won’t lose any content.
We recommend doing two kinds of backups:
- Create backup environments: Clone your existing “master” environment into a backup environment (name it “backup-master-before-compose”). Don’t make any changes to this environment.
- Export your content using our export tool: This export will save a copy of your current “master” environment on your local machine. You probably won’t need this local backup but it is better to be safe than sorry.
Optional: Back up the content version history of your existing pages
In case the content version history (also called content snapshots) is important for you to preserve for audit trail purposes, follow the steps mentioned in this section. Otherwise, this step does not create any actionable artifacts or assist in the migration.
During the migration of your existing pages you will create Compose-compatible copies of your pages and discard the original entry once finished. That means that the content history of the pages won’t be preserved after the migration.
Programmatically iterate through all page entries using the entries collection endpoint. For each entry:
- Call all snapshots of each entry.
- Store these snapshots somewhere. How you do this is up to you, but consider a JSON file per entry.
You will likely need to build in throttling into the script that performs the above in order to honor the content management API rate limits.
Adapting your content model to support Compose
Now that your content is backed up and you have a migration plan ready, it’s time to migrate your content model and pages.
First, check if you can install Compose in your environment:
- Compose needs content types with “page” and “seo” content type IDs to work. If you don't already have content types with IDs of "page" or "seo", you can use the guided setup that comes with Compose to create these content types for you (see installation steps below).
- If your content model already has content types with “page” or “seo” IDs, you must recreate the content type with the conflicting IDs, and its entries under another content type ID. The necessary steps will be described in the next section.
Resolving content type ID conflicts
This step is only required if you have content types with the “page” or “seo” IDs which would prevent you from installing Compose.
If there is an existing content type with the ID “page” or “seo”, you will need to duplicate this content type with another name and ID.
One way to do this is via a migration script using the
transformEntriesToType function which has the additional advantage that it allows you to update all links to page entries to point to the new copy. See this GitHub Gist for an example script.
To install Compose:
- Before the installation, make sure you’re working in the space and environment that are dedicated for Compose.
- Install Compose following the steps described here.
- Open Compose once the installation is done.
Create content types for Compose
When you first open Compose, you’ll be given the choice to do a “Quick start” or “Guided setup” of your space. Both options will install the necessary content types for the app, but we recommend the “Guided setup” option for established Contentful spaces because it won’t install any sample content into your space.
Complete at least steps 1 and 2 of the guided setup process to create Compose-specific content types (“Compose: Page” and “Compose: SEO”) and your first page type (in our example below, the page type is called “Post Page”).
If the existing content type has additional page or SEO metadata fields, you can extend the Compose content model with these fields.
Migrate existing pages to Compose
Now that you have installed Compose and created the required content types, you are ready for the most important step: migrating existing content types to Compose.
Go through the steps described below to migrate your existing content type and entries of this content type to Compose. In our example, we will migrate the existing content type called “Post”.
The diagram below illustrates the starting point for our example. There is a single content type called “Post”, and a single entry of that content type called “Hello World”.
Set up Compose-specific content types
Create "Compose: Page" and "Compose: SEO" content types: This is a one-time change that is described above. If you haven’t yet created these content types as part of the Compose guided setup, please do so before you start this migration process.
Migrate existing content type to Compose page type
In this phase, you will create a page type and move the content from your existing content type to this page type. For each of your existing content types, an individual page type needs to be created. Follow the steps below to create a page type and migrate your existing content type to it.
The steps below have to be performed individually for each page type that you will create..
I. Create a new page type
- Create a new page type. Add the new page type to Compose.
The page type will hold only content fields of the existing content types..
II. Copy content fields
- Add a “Content” single reference field to your existing content type.
- For each entry of your existing content type, create a corresponding entry of the newly created page type.
- Copy the relevant field values from each entry of your existing content type to the corresponding page type entry.
- Link the newly created page type entry to the “Content” field in the existing content type entry.
III. Copy SEO fields
- For each entry of your existing content type, create a “Compose: SEO”-type entry.
- Copy the relevant field values from each entry of your existing content type to the corresponding “Compose: SEO”-type entry.
- Link the newly created “Compose: SEO” entry to the “SEO” field in your existing content type entry.
IV. Copy “Compose: Page” fields and references
- For each entry of your existing content type, create a “Compose: Page” entry.
- Copy the remaining fields (mostly Title and Slug) along with the “Content” and “SEO” pointers from each entry of your existing content type to the corresponding “Compose: Page” entry.
V. Delete original content
- Delete existing content type and entries.
Content model and entries after the migration
As a result of the migration, a new content model and content entries are created as displayed in the diagram below:
You can now work with these entries in Compose.
Test the migrated content in Compose
Now that you have adapted your content model to support Compose and completed the content migration, you should be able to view and manage pages within Compose.
Before you move on to adjust your code to support the new content model it is important to verify if the migration was successful:
- Are all pages visible in Compose?
- Are all page types available and have the right amount of pages?
- Are the page and SEO settings correctly migrated and contain the expected values?
- Is the page content correct and complete?
- Are references and links between entries and assets correct?
In case you spot any errors you can either manually correct them or adjust your migration scripts and re-run the migration in a new environment.
Step 3: Code changes to your website
With the content model and content changes in place, you now will need some code changes for your frontend applications to load and render Compose pages.
In your code you most likely will have functionality to resolve URLs using slug fields on your legacy page types which triggers API calls to Contentful to load the requested page data. You will need to adjust all existing page types to make API calls to the top-level “Compose: Page” content type.
Depending on which Content Delivery API you use there are some things to consider:
- GraphQL API - Refactor your page template content fetching to add in the additional “Compose: Page” layer to your content model.
- Content Delivery / Preview API - Extend any include parameter on an entries collection call with an additional layer. Watch out for new circular references due to this change.
Once the pages load and render, you will also need to adjust the rendering of page and SEO metadata.
You can see examples of how to load and render web pages in our open source Next.js repo on Github.
Additionally you might need to revise other parts of your code base that deal with pages: rendering links to pages, website navigation, sitemaps, etc.
Test the code changes on a staging server
Verify that your website works as expected:
- Are all pages available and render correctly?
- Do links between pages still work?
Step 4: Make your changes live
We highly recommend having a content freeze (no content created or edited) while bringing changes live, in case any issues occur and your website has to be rolled back to an earlier version..
After completing and thoroughly testing the content and code changes, the next step is to bring the changes to production.
Apply content migration to production environment
First you will need to apply the content migration from the dedicated Compose environment to your production environment. There are two recommended ways of doing this:
- Use environment aliases to swap out your production environment.
- Apply all migration scripts to your production environment. (Be sure to create a backup environment first).
You can find more details for both approaches in our tutorial for deploying changes with environment aliases.
Deploy new version of the website
Once the content model changes are applied to your production space environment it is time to deploy your code changes to your production server.
To minimize downtime we recommend orchestrating your deployment using a CI/CD pipeline.
Once deployed, do a last round of testing to check if your website works as expected.
Revise space configuration
The last step is to revise some space settings that might be affected by the content model changes:
Revisit your webhooks - Make sure your automations are configured to listen to events for the new “Compose: Page” content type. It may affect any automations or integrations (e.g., your build process, search indexing) if you don’t.
Revisit any custom roles - For Enterprise customers with access to custom roles and permissions, adjust any custom roles that reference specific content types, and adjust them to work with Compose.
Reconfigure the website previews for each page type: This will make it easy for editors to preview content changes within Compose.