DEV Community: Michael Donaldson

Visual Content Previews with Vue Storefront 2

Michael Donaldson — Wed, 18 Aug 2021 09:55:33 +0000

In the past couple of articles, I've walked through integrating a headless CMS and also implementing content personalisation with Vue Storefront 2.

In this article, we're going to take things even further and learn how to integrate Vue Storefront 2 with LexasCMS's visual content previews.

Content editors are often left guessing at how content will appear once published. Visual previews are instrumental in removing the need for this guesswork and give content editors the confidence that they need to work efficiently.

In addition to this, LexasCMS's visual previews integrate deeply with its personalisation and scheduling features, enabling content editors to see exactly how any (past, present or future) content will appear through the eyes of specific visitors.

Awesome right? Let's take a look at how it works 👇.

Tutorial

Just like last time, we're going to be using the store which you created in the previous tutorials as a starting point. If you haven't completed these, don't worry as I'll also provide some instructions to get you caught up 🙂.

Pre-requisites

As with the previous tutorials, before getting started it's recommended that you have the following:

Basic knowledge of Vue.js and Nuxt.js
Node.js v12 or higher installed
Yarn installed
A LexasCMS account - Click here to start a free trial

Step 0: Getting caught up

Note: If you've already completed the previous tutorials, feel free to skip this section.

For those of you you haven't, simply follow the steps below to catch up.

Step 0.1: Create a new space on LexasCMS

First you'll need to create a new space in LexasCMS which uses the E-commerce Tutorial (Vue Storefront) template.

To do this, simply follow Step 1 of the first tutorial which you can find here.

Step 0.2: Clone source code for previous tutorial

After creating your space, you can clone the final source code for the previous tutorial by running the following command:

git clone --branch part-2-personalisation https://github.com/LexasCMS/tutorial-vsf-next.git

Step 0.3: Install project dependencies

Once you've cloned the source code, navigate into your project directory and install the projects dependencies using the commands below:

cd tutorial-vsf-next
yarn install

Step 0.4: Configure your space ID

Open the middleware.config.js file within your code editor and replace process.env.LEXASCMS_SPACE_ID within the lexascms configuration with your actual space ID.

Note: You can find your space ID by navigating into the Settings > General section of your space control panel.

 module.exports = {
   integrations: {
     // ... 

     lexascms: {
       location: 'vsf-lexascms/server',
       configuration: {
-        spaceId: process.env.LEXASCMS_SPACE_ID
+        spaceId: 'YOUR_SPACE_ID'
       }
     }
   }
 };

Step 0.5: Start development server

After your projects dependencies are installed, start your development server using the command shown below:

yarn dev

Once your development server is up and running, navigate to http://localhost:3000/ in your web browser and you should see something like the below screenshot.

0.6: Setup personalised content (optional)

While optional, we recommend completing steps 1-4 of the previous tutorial.

In addition to allowing you to gain an understanding of LexasCMS's personalisation features, it will also enable you to experience the full benefits of the visual preview tool later on.

Step 1: Configure your preview URL

The first thing we need to do is configure a preview URL which LexasCMS can use to load your project within its visual preview tool.

To do this, navigate to the Settings > Previews section of your space, and click on the Create Preview button.

Create a preview with the following attributes:

Name: Local Development
Preview URL: http://localhost:3000

Step 2: Create an API key

When retrieving content previews from LexasCMS's Content Delivery API, you must authenticate your requests by providing an API key.

Navigate to the Settings > API Keys section of you space, and click on the Create an API Key button.

Create a new API key named Local Development, being sure to enable the Content Delivery API (Preview) permission as shown in the screenshot below.

Once the API key has been created, take note of the generated token, as you'll need it later.

Step 3: Install LexasCMS code snippet

In order for LexasCMS's visual preview tool to function correctly, you must install a small code snippet.

This code snippet must be embedded on every page and allows your project to communicate with LexasCMS's visual preview tool.

To install the code snippet, make the following changes to your projects nuxt.config.js file:

 // ...

 export default {
   // ...

   head: {
     // ...

-    script: []
+    script: [
+      {
+        hid: 'lexascms',
+        defer: true,
+        innerHTML: '(function(e,t){void 0!==e.addEventListener&&e.addEventListener("load",function(){var e=t.getElementsByTagName("script")[0],n=t.createElement("script");n.type="text/javascript",n.async=!0,n.src="https://static.lexascms.com/lexascms.js",e.parentNode.insertBefore(n,e)},!1)})(window,document)'
+      }
+    ],
+    __dangerouslyDisableSanitizersByTagID: {
+      lexascms: ['innerHTML']
+    }
   }

   // ...
}

Step 4: Configure API key

Next, in your projects middleware.config.js file, configure your API key by adding the apiKey property to your lexascms configuration as follows:

Note: Be sure to replace YOUR_API_KEY_TOKEN with the generated token for the API key which you created in step 2.

 module.exports = {
   integrations: {
     // ... 

     lexascms: {
       location: 'vsf-lexascms/server',
       configuration: {
-        spaceId: '...'
+        spaceId: '...',
+.       apiKey: 'YOUR_API_KEY_TOKEN'
       }
     }
   }
 };

Step 5: Update homepage source code

When LexasCMS loads your project within it's visual preview tool, it provides a pre-configured request context via the lexascmsRequestContext query parameter.

If you followed the previous tutorial, you'll remember that we used the request context to set the values of our audience attributes when making a request to the Content Delivery API.

When the lexascmsRequestContext query parameter is present, we should pass its value as the request context for all requests to LexasCMS, instead of defining our own.

As an example of how to do this, open the pages/Home.vue file and update the setup function to as follows:

 // ...

 setup(_, context) {
   const { content: promoBanners, search } = useContent();

   onSSR(async () => {
+    let requestContext;
+    const { lexascmsRequestContext, localTemp } = context.root.$route.query;
+    if (lexascmsRequestContext !== undefined) {
+      requestContext = lexascmsRequestContext;
+    } else {
+      requestContext = {
+        audienceAttributes: {
+          localTemperature: localTemp ? parseInt(localTemp, 10) : null
+        }
+      };
+    }
+
     await search({
       type: 'collection',
       contentType: 'promoBanner',
       params: {
         include: 'backgroundImage'
       },
-      context: {
-        audienceAttributes: {
-          localTemperature: context.root.$route.query.localTemp ? parseInt(context.root.$route.query.localTemp, 10) : null
-        }
-      }
+      context: requestContext
     });
   });

   return { promoBanners }
 },

 // ...

As you can see, this change will first check for the existence of the lexascmsRequestContext query parameter before attempting to build its own request context.

Step 6: Previews in action

After saving your changes, restart your development server and head back into LexasCMS. Navigate to the Content Preview section of your space.

You should see your project appear in the main visual preview panel.

To the right of the preview, there will be a sidebar which allows you to control the context of the preview.

Just like we did in the previous tutorial, let's see what our store looks like when being viewed by a customer whose local temperature is 5°C.

Click the Update link next to the Audience Attributes heading in the preview context sidebar to reveal the Update Audience Attributes modal.

From the modal, click the Add Attribute button, select the Local Temperature attribute and set it's value to 5.

Click on the Confirm button, followed by the Update Preview button in the preview context sidebar. This will apply your changes and reload the preview in the specified context.

You should now see that the preview has updated, and that the content from the Cold Climate variation which we created in the previous tutorial is being displayed.

What did I say, awesome right? ✨

Live demo and GitHub repo

A live demo of this tutorial as well as its source code can be found using the links below:

Live demo: https://lexascms-tutorial-vsf-next.vercel.app/
Source code: https://github.com/LexasCMS/tutorial-vsf-next/tree/part-3-visual-previews

Summary

We'll definitely be writing more about Vue Storefront in the future, however this marks the end of our Vue Storefront 2 tutorial series.

To recap, in this series of tutorials we've covered the following:

Integrating a headless CMS
Personalised Content
Visual Content Previews (this article)

These tutorials have demonstrated not only how simple it is to integrate LexasCMS with Vue Storefront 2, but also the additional benefits that it brings to your e-commerce store.

Did you find this series of tutorials helpful? Tweet at us to let us know!

Implementing Personalised Content with Vue Storefront 2

Michael Donaldson — Wed, 11 Aug 2021 13:29:50 +0000

A couple of weeks ago I wrote a tutorial which walked you through integrating a headless CMS with Vue Storefront 2.

This week we're going to take things a bit further, and I'll be showing you how you can use LexasCMS to bring personalised content to your e-commerce store.

What is personalisation?

Over the past several years personalisation has become an increasingly important part of e-commerce. So before we dive into the tutorial itself, it's probably a good idea to take a moment to explain what personalisation actually means.

In e-commerce, personalisation refers to delivering content (e.g. promotions and product recommendations) which is tailored to the current customer based on information which is known about them.

For example, if based on their purchase/browsing history you knew that a customer had an interest in shoes, you could tailor the promotions that they were shown to include your latest offers on footwear.

Historically, personalisation has always been something which was reserved for larger companies who could afford access to expensive personalisation platforms. However tools and platforms (such as LexasCMS 😉) are now emerging which make personalisation accessible to companies of all sizes.

Tutorial

Now that we have a clear understanding of what personalisation is, let's get to the tutorial!

In this tutorial, we're going to personalise an e-commerce store's homepage banner based on the temperature in the current customers location.

To keep it simple, we'll base the personalisation on the value of a query parameter. However, in the real world you would likely base it on something more realistic such as the output from a realtime weather API (e.g. OpenWeather API).

As a starting point, we'll also be using the store which you created in the previous articles tutorial.

If you didn't complete this tutorial, that's not a problem as I'll also provide instructions on how to get caught up 😉.

Pre-requisites

As with the previous tutorial, before getting started it's recommended that you have the following:

Basic knowledge of Vue.js and Nuxt.js
Node.js v12 or higher installed
Yarn installed
A LexasCMS account - Click here to start free trial

Step 0: Getting caught up

Note: If you've already completed the tutorial from the previous article, feel free to skip this section.

If you haven't, you can simply follow the steps below to catch up 🙂.

Step 0.1: Create a new space on LexasCMS

First you'll need to create a new space in LexasCMS which uses the E-commerce Tutorial (Vue Storefront) template.

To do this, simply follow Step 1 of the previous articles tutorial which you can find here.

Step 0.2: Clone source code for previous tutorial

After creating your space, you can clone the final source code for the previous tutorial by running the following command:

git clone https://github.com/LexasCMS/tutorial-vsf-next.git

Step 0.3: Install project dependencies

Once you've cloned the source code, you'll need to navigate into your project directory and install the projects dependencies using the commands below:

cd tutorial-vsf-next
yarn install

Step 0.4: Configure your space ID

Open the middleware.config.js file within your code editor and replace process.env.LEXASCMS_SPACE_ID within the lexascms configuration with your actual space ID.

Note: You can find your space ID by navigating into the Settings > General section of your space control panel.

 module.exports = {
   integrations: {
     // ... 

     lexascms: {
       location: 'vsf-lexascms/server',
       configuration: {
-        spaceId: process.env.LEXASCMS_SPACE_ID
+        spaceId: 'YOUR_SPACE_ID'
       }
     }
   }
 };

Step 0.5: Start development server

After your projects dependencies are installed, start your development server using the command shown below:

yarn dev

Once your development server is up and running, navigate to http://localhost:3000/ in your web browser and you should see something like the below screenshot.

Step 1: Create new audience attribute

By this point you should have either completed the previous tutorial, or followed the steps in the previous section to get caught up!

In LexasCMS, personalisation works by allowing you to segment your customers into groups called Audiences. These audiences can then be targeted with specific variations of your content.

Audience attributes are the characteristics (e.g. age, gender, location etc.) which are used to segment your customers into audiences.

First things first, we'll need to create a new audience attribute.

From your space's control panel, navigate to the Audiences > Attributes section. Once there, click on the Create Attribute button and create a new attribute with the following values.

Name: Local Temperature
Key: localTemperature
Type: Number

Step 2: Create new audience

Next you'll need to create a new audience. As mentioned earlier, audiences are essentially groups which allow you to segment your customers based on custom rules and conditions which are defined by you.

We're going to create an audience which captures customers whose local temperatures are less than 10°C.

Navigate to the Audiences > Audiences section and then click on the Create Audience button.

Create an audience with the following values:

Name: Cold Climate
Key: coldClimate

Step 3: Configure audience conditions

Once your audience has been created, you'll be automatically taken to the Edit Audience screen. This is where you define the rules and conditions which determine whether or not a customer should be included within this audience.

Add a new Attribute condition by clicking the Add Condition button.

On the newly created condition, select the Local Temperature attribute, change the comparator to Less Than and enter 10 in the value field.

Click the Save Changes button and you should be left with an audience configuration which looks as follows:

Step 4: Target your audience with a content variation

In this step we're going to edit one of the existing promo banners and add a new variation which is targeted at our newly created audience.

Navigate to the Content section and open the promo banner named First promo banner from LexasCMS.

Within the item, you'll see that there is currently just one variation named Default. This is the variation of this promo banner which is currently being displayed on your homepage.

Click the Create Variation button to create a new variation.

Enter a name for your new variation and then click the Create Variation button.

Note: Feel free to name the new variation whatever you'd like, however I'm going to call it Cold Climate.

Once your new variation has been created, you'll automatically be taken to the content editing screen.

From here, fill out the content fields as specified below:

Heading: 10% off all winter coats!
Sub Heading: Cold Weather Collection
Button Text: Learn More
Background Image: Save and upload this image

Next up, we need to assign our new variation to the audience which we created earlier.

In the sidebar to the right of the screen, you'll see an Audience heading as shown in the screenshot below.

This tells you which audience the variation is currently assigned to, but since it isn't yet assigned to any there will be an Add Audience link instead.

Click the Add Audience link to open the Update Audience modal and then within the modal, select the Cold Climate audience which you created earlier.

Click the Confirm button to assign the selected audience.

Now that an audience has been assigned to our new variation, it will only be delivered to customers whose characteristics match the conditions which we defined earlier.

All that's left now is to activate the Published toggle and click the Save Changes button to apply all of your changes.

Step 5: Update homepage to send audience attributes

You may have noticed that up until this point we haven't touched a single line of code. This is actually part of LexasCMS's design and means that content editors can have complete freedom to experiment without the need to involve developers.

Having said that, there is one small code change which we need to make before LexasCMS can begin to personalise your content.

In your code editor, open your pages/Home.vue file and update the setup method as follows:

<script>
// ...

export default {
  // ...

  setup(_, context) {
    const { content: promoBanners, search } = useContent();

    onSSR(async () => {
      await search({
        type: 'collection',
        contentType: 'promoBanner',
        params: {
          include: 'backgroundImage'
        },
        context: {
          audienceAttributes: {
            localTemperature: context.root.$route.query.localTemp ? parseInt(context.root.$route.query.localTemp, 10) : null
          }
        }
      });
    });

    return { promoBanners }
  },

  // ...
}
</script>

All that we've done is added a couple of arguments to the setup function and added the context parameter to our call to the search function.

This context parameter allows you to (amongst other things) provide values for each of your defined audience attributes.

As explained earlier, to keep things simple we're pulling the value of our localTemperature attribute from a query parameter. We're also passing it through the parseInt function to ensure that it is of the correct type when provided to LexasCMS.

Once you've saved your changes, go back to your browsers and reload your projects homepage (http://localhost:3000/).

You should see that nothing has changed and that it looks exactly as it did at the start of this tutorial. This is because we haven't yet specified the localTemp query parameter.

Reload the homepage again, but this time also add the localTemp query parameter with any value less than 10 (e.g. http://localhost:3000/?localTemp=5).

This time, you should see that your homepage has changed and that it's now displaying the content from the Cold Climate variation which you created earlier.

And that's all there is to it! 🙌

All of the heavy lifting is handled for you by LexasCMS's Content Delivery API, meaning that you don't need to make any changes to your templates or add any complicated logic to your application code.

Live demo and GitHub repo

A live demo of this tutorial as well as its source code can be found using the links below:

Live demo: https://lexascms-tutorial-vsf-next.vercel.app/
Source code: https://github.com/LexasCMS/tutorial-vsf-next/tree/part-2-personalisation

Summary

Hopefully during this tutorial, I've managed to show you that implementing content personalisation doesn't have to complicated.

Using LexasCMS, it's incredibly simple to integrate personalisation in a way which is both easy to maintain for developers and also provides content editors with the flexibility that they need to experiment.

In our next post, we're going to be taking this project even further and I'll be showing you how to use LexasCMS's visual preview feature to preview your website through the eyes of your customers.

Integrating a headless CMS with Vue Storefront 2

Michael Donaldson — Wed, 28 Jul 2021 14:05:56 +0000

With the recent rise of composable commerce, integrating headless CMSes into e-commerce websites is becoming increasingly common. One such tool which makes this incredibly straight forward, is Vue Storefront 2.

For those of you who are new to it, Vue Storefront 2 is the latest version of Vue Storefront, which is a platform-agnostic PWA framework for creating e-commerce websites.

In this post we’re going to walk you through how to integrate a headless CMS (specifically LexasCMS 😉) with Vue Storefront 2.

Tutorial

So enough with the preamble, let’s get straight to it! 🚀

In this tutorial we're going to take a freshly generated Vue Storefront 2 project, and replace the homepage hero banner with one that is managed by your headless CMS (in this case LexasCMS).

Pre-requisites

Before getting started with the tutorial, it is recommended that you have the following:

Basic knowledge of Vue.js and Nuxt.js
Node.js v12 or higher installed
Yarn installed
A LexasCMS account - Click here to start free trial

Step 1: Create a new space on LexasCMS

From within your organisation, create a new space by clicking on the Create Space button and filling out the required information (any plan type will work fine).

Once your new space has been created, open it, and you will be presented with a Select Starter Template modal.

From the modal, select the 'E-commerce Tutorial (Vue Storefront)' template, and then click the Import Template button.

This template will automatically create the content types and sample content which will be needed for this tutorial.

Step 2: Create a new Vue Storefront 2 project

We'll be using the Vue Storefront CLI to generate a new project. If you don't already have this installed, you can install it by running the following command in your terminal:

yarn global add @vue-storefront/cli

Now, generate a new Vue Storefront 2 project using the command below:

Note: When prompted to choose an integration, just select commercetools.

vsf init lexascms-tutorial

This command will create a new lexascms-tutorial directory which will contain the code for your new project.

Once it has finished, navigate into the new project directory and install your projects dependencies:

cd lexascms-tutorial
yarn install

After your projects dependencies are installed, start your development server using the command shown below:

yarn run dev

Once your development server is up and running, navigate to http://localhost:3000 in your web browser and you should see something like the below screenshot.

Step 3: Install LexasCMS integration

Before content can be retrieved from your headless CMS, you'll need to install and configure the Vue Storefront integration of your chosen CMS (in this case LexasCMS).

To install the LexasCMS integration for Vue Storefront, run the following command:

yarn add vsf-lexascms

Once the installation has finished, register the vsf-lexascms integration in your projects nuxt.config.js file as follows:

export default {
  // ...

  buildModules: [
    // ...

    ['vsf-lexascms/nuxt']
  ]

  // ...
};

Next, open the middleware.config.js file in the root of your project and add the following configuration:

Note: Be sure to replace YOUR_SPACE_ID with your actual space ID, which can be found in the Settings > General section of your space control panel.

module.exports = {
  integrations: {
    // ...

    lexascms: {
      location: 'vsf-lexascms/server',
      configuration: {
        spaceId: 'YOUR_SPACE_ID'
      }
    }
  }
};

Now that the integration has been installed and configured, content can be retrieved using the useContent composable. Before we make any changes to our homepage, let's take a look at how it works.

The useContent composable is imported directly from your CMS integration like so:

import { useContent } from 'vsf-lexascms';

The composable then provides access to a search function, and three other properties: content, loading and error.

const { search, content, loading, error } = useContent();

search is a function and is used for retrieving content from your CMS (in this case LexasCMS)
content, loading and error are all computed properties which are populated by the search function
- content contains the content which was retrieved by the search function
- loading is a boolean which communicates whether the search function is currently running or not
- error is null unless an error is thrown by the search function, in which case this contains the error message

Usage of the search function will vary depending on the CMS that you're integrating with. However, you can find the full documentation for the LexasCMS integration here.

Step 4: Update homepage

Now that you've seen how the useContent composable works, let's use it to fetch the content for your homepage's hero banner.

Start by opening the pages/Home.vue file in your project, and adding the below import statements.

You'll notice that we're also importing the onSSR helper function from Vue Storefront. We'll use this to ensure that content is only fetched during server-side rendering.

<script>
// ...
import { onSSR } from '@vue-storefront/core';
import { useContent } from 'vsf-lexascms';

export default {
  // ...
}
</script>

Next, define a setup function as shown below.

This function uses the useContent composable and onSSR helper function to retrieve all of the promo banners from LexasCMS. These are then made available to your template as the promoBanners variable.

<script>
// ...

export default {
  // ...

  setup() {
    const { content: promoBanners, search } = useContent();

    onSSR(async () => {
      await search({
        type: 'collection',
        contentType: 'promoBanner',
        params: {
          include: 'backgroundImage'
        }
      });
    });

    return { promoBanners }
  },

  // ...
}
</script>

Now that we've retrieved the promo banners, we just need to display them!

Scroll back to the top of the pages/Home.vue file and replace the current usage of the SfHero component so that it looks as follows:

<template>
  <div id="home">
    <SfHero class="hero">
      <SfHeroItem
        v-for="promoBanner in promoBanners"
        :key="promoBanner.id"
        :title="promoBanner.heading"
        :subtitle="promoBanner.subHeading"
        :button-text="promoBanner.buttonText"
        :image="promoBanner.backgroundImage.url"
      />
    </SfHero>

    <!-- ... -->
  </div>
</template>

This will loop through the promoBanners variable from the previous step, and render each of the retrieved promo banners using the SfHeroItem component from Storefront UI.

Restart your development server and navigate to http://localhost:3000 in your web browser.

You should see that the homepage hero banner is now being powered by your CMS content.

Congratulations! You successfully integrated a headless CMS into a Vue Storefront 2 project 🎉.

Live demo and GitHub repo

A live demo of this tutorial as well as its source code can be found using the links below:

Live demo: https://lexascms-tutorial-vsf-next.vercel.app
Source code: https://github.com/LexasCMS/tutorial-vsf-next

Summary

In this tutorial, you have learned how simple it is to fetch content from a headless CMS using the useContent composable in Vue Storefront 2.

In future posts we'll show you how to take things further and implement features such as personalised content and visual previews using LexasCMS.

Thanks for reading! 🤘

Using a Headless CMS to Personalize E-Commerce With LexasCMS

Michael Donaldson — Wed, 24 Mar 2021 16:11:35 +0000

Why create a new headless CMS?

Hey 👋, I’m Mike, one of LexasCMS’s co-founders.

This is probably one of the first questions people ask when you tell them that you’ve created another new headless CMS for personalization. Give me a moment to explain, and you’ll see that it’s worth your time. 😉

There’s somewhat of a running joke in the development community that almost every developer will decide to build a custom CMS at some point in their career. In fact, back in the mid/late 2000s, pretty much every web agency actually had its own bespoke CMS.

Fast forward to 2021, and the way people consume content has changed radically. Users not only expect content to be accessible from all of their various platforms and devices, but they also expect it to be consistent.

As a result, the past decade has seen an explosion of new headless CMSes being launched to meet the evolving demands of the world's digital ecosystem.

So to take it back to the original question, why did we create LexasCMS?

Well, while it’s true that there are a stunningly large number of headless CMSes to choose from, there are none that really hit the sweet spot when it comes to e-commerce.

Important features–such as personalization, scheduling, and visual previews–are often either missing, not flexible enough, or require too much custom integration work.

By focusing on e-commerce, we can ensure that LexasCMS provides the tools and features that storefront owners need to drive sales and run successful e-commerce businesses.

What is LexasCMS?

LexasCMS is an e-commerce focused headless CMS bootstrapped and launched by myself and fellow co-founder David Bond in June 2020.

I’ve known David almost my entire life. After going through school and college together, we began working as freelancers in 2010, working on projects of all shapes and sizes.

Naturally, from the beginning, we had our own bespoke CMS (who didn’t, right?), which we would use as the base for most of our client projects. Over time, we continued to develop new features, fix bugs, and at one point, even began the process of packaging it for commercial purposes.

Ultimately, we decided that with the headless CMS's rise, it probably wasn’t the right direction. Instead, we opted to use what we’d learned over the best part of a decade to create what would eventually become LexasCMS.

During the initial planning for LexasCMS, we were conscious that we didn’t want to create “yet another headless CMS”. It needed to provide specific value which couldn’t be found in existing solutions.

Around this time, we decided to focus on e-commerce and providing the specific features required by modern online businesses.

👥 Content Personalization - Personalization is one of the biggest features of modern e-commerce websites. With LexasCMS, editors can create multiple variations of their content and then target them at specific audiences based on their individual characteristics.

🗓 Content Planning / Scheduling - Many e-commerce businesses plan their content weeks or even months in advance. LexasCMS allows you to input precisely how your content should change over time and then handles the rest for you. No more babysitting late-night content deploys. 🙌

👁 Visual Previews - Navigate around your website in the context of specific visitors. You can even control the date/time of the preview context to see how it would look for them in the past or future.

⚙️ Third-Party Integrations (Coming Soon) - LexasCMS will soon be able to link product and category data from your e-commerce platform directly with your CMS content. This will make it painless to implement features such as personalized product recommendations.

What’s this post going to be about?

In this post, I will show you how to create a personalized e-commerce store using LexasCMS, Snipcart, and Next.js. I’ll also show you how to set up visual previews so that you can see how your website appears through the eyes of specific visitors.

Before we get into the tutorial itself, I want to take a moment to explain what we mean by personalization and how LexasCMS makes it easier.

Many years ago, personalization was as simple as including a customer’s name within a marketing email. Nowadays, requirements are a lot more in-depth and can refer to anything from displaying a customer’s name all the way through to customizing the contents of an entire webpage.

Personalization is usually based on known information about the current customer. This information could be anything, but common examples include basic profile data, previous browsing/purchase history, their current location, or even the weather in their current location.

Before LexasCMS, if you wanted to personalize your CMS content, you needed the help of a third-party personalization platform. This platform would be used to determine which audiences a customer was in, and then developers would use that information to manually query for the correct content from your CMS.

The problem with this approach is that it places a lot of burden on the developer to calculate and retrieve the correct content. Additionally, using two separate services creates a disconnect between the content management and personalization configuration, which in some cases can also limit the freedom for content editors to experiment. Content editors must also learn and jump between two separate applications, adding further friction to the content management process.

LexasCMS not only removes the need for an additional third-party platform but also removes almost all of the personalization logic from your application. Simply ask LexasCMS for a piece of content, describe the customer who is making the request, and it will automatically send back the most relevant variation of that content.

This is possible because LexasCMS holds all of the audience and personalization configuration. Content editors can control which variations of content should be delivered to specific audiences, enabling LexasCMS’s Content Delivery API to automatically calculate which content is most relevant for any request.

Well! With all that out of the way, let’s move on to the tutorial! 🤓

❗️ Fair warning: This is a pretty long tutorial, so if you just want to see the final result or the source code, feel free to skip to the end.

Creating a personalized e-commerce store with LexasCMS, Snipcart & Next.js

As mentioned earlier, we’re going to use Next.js for our example e-commerce store, but why Next.js?

Editor note: We have a great video with our friend Colby Fayock explaining what is Next.js here.

The main reason is that Next.js makes it incredibly simple to switch between Server-Side Rendering (SSR) and Static Site Generation (SSG) on a per-route basis.

Since we’re going to be personalizing some of the pages on our store, these routes will need to be rendered on the server so that the content can be tailored based on the current visitor’s characteristics.

On the flip side, routes that don’t typically need to be personalized–such as product pages–can be statically generated to improve performance.

Pre-requisites

Before getting started with the tutorial, it is recommended that you have the following:

Basic knowledge of React and Next.js
Node.js v12 or higher installed
Yarn installed
A LexasCMS account - Click here to start a free trial.
A Snipcart account - Click here to create a free account.

Step 1: Create a new space on LexasCMS

Start by signing into your account and then either creating a new organization or navigating into an existing one.

From within your organization, create a new space by clicking on the Create Space button and filling out the required information. When choosing a plan type, please select Starter or above, as the hobby plan does not have access to LexasCMS’s personalization features.

Once your new space has been created, open it, and you should be presented with a Select Starter Template modal.

Go ahead and select the ‘E-commerce Tutorial (Snipcart)’ template.

To save you the trouble of doing it yourself, this template will automatically create all of the content types and sample content that you will need to complete this tutorial.

For those interested in what exactly the template created, feel free to browse around the Content and Content Model sections of your space.

Step 2: Create a new Next.js project

Next up, we’re going to create a new project based on Next.js. You can do so by running the following command in your terminal.

yarn create next-app lexascms-snipcart-tutorial

This command will create your new project and install its dependencies within a directory named lexascms-snipcart-tutorial.

Once it has finished, navigate into your new project directory and start your development server using the commands shown below.

cd lexascms-snipcart-tutorial
yarn run dev

After your development server is up and running, navigate to http://localhost:3000 in your web browser, and you should see something like the below screenshot.

Step 3: Install and configure TailwindCSS

Nobody likes to look at an ugly website, so for the sake of your eyes, we’re going to install TailwindCSS.

If you haven’t used TailwindCSS before, you should definitely check it out! It’s an awesome utility-first CSS framework that was created by Adam Wathan and Steve Schoger.

Since TailwindCSS is actually a PostCSS plugin, we’ll also need to install that as well.

Install both modules by running the following command from the root of your project directory:

yarn add --dev postcss tailwindcss

Next, you’ll need to configure PostCSS to use the TailwindCSS plugin. You can do this by creating a file named postcss.config.js in the root of your project directory with the following contents:

module.exports = {
  plugins: [ 'tailwindcss' ]
};

Finally, open the styles/global.css file, and replace its content with the following:

@tailwind base;
@tailwind components;
@tailwind utilities;

Step 4: Create LexasCMS helper

Before we start creating our store, we’ll need to create a helper which will be used to fetch content from LexasCMS using its GraphQL based Content Delivery API.

Let’s start by installing some dependencies:

yarn add graphql graphql-request base-64

Create a new file named lib/lexascms.js with the following contents:

import Base64 from 'base-64';
import { GraphQLClient } from "graphql-request";

export function request({ query, variables, requestContext }) {
  // Define space ID
  const spaceId = 'YOUR_LEXASCMS_SPACE_ID';
  // Define API key
  const apiKey = null;
  // Define headers
  const headers = {};
  // Add Authorization header if required
  if (apiKey !== null) {
    headers['Authorization'] = `Bearer ${apiKey}`;
  }
  // Handle LexasCMS request context
  if (requestContext !== undefined) {
    let lexascmsRequestContext = requestContext;
    if (typeof lexascmsRequestContext !== 'string') {
      lexascmsRequestContext = Base64.encode(JSON.stringify(requestContext));
    }
    headers['x-lexascms-context'] = lexascmsRequestContext;
  }
  // Create client
  const client = new GraphQLClient(`https://${spaceId}.spaces.lexascms.com/delivery/graphql`);
  // Send request
  return client.request(query, variables, headers);
}

Still, in the lib/lexascms.js file, replace YOUR_LEXASCMS_SPACE_ID with your actual space ID, which can be retrieved from the Settings > General section of your space control panel.

Note: To keep things simple, we’re just hardcoding the space ID. In a real-world project, you would most likely want to retrieve this value from a pre-configured environment variable.

Step 5: Create a homepage

We’re going to start by creating a layout component. This component will wrap every page in our project to include common elements such as headers and footers.

Create a new file at components/layout.js and inside it paste the following:

import Link from 'next/link';

export default function Layout({ children }) {
  return (
    <>
      <div className="px-5">
        <div className="max-w-screen-lg mx-auto pt-8 pb-16">
          <div className="flex items-center justify-between mb-10">
            <h1 className="text-4xl font-bold">
              <Link href="/">My Shop</Link>
            </h1>
          </div>

          {children}
        </div>
      </div>
    </>
  )
}

Next, navigate to the pages/index.js file and replace its contents with the following:

import Link from 'next/link';

import Layout from '../components/layout';
import { request } from '../lib/lexascms';

export default function Home({ homepage }) {
  return (
    <Layout>
      <div className="flex flex-col gap-2 items-center justify-center bg-gray-200 text-white h-96 rounded bg-cover bg-center" style={{backgroundImage:`linear-gradient(0deg, rgba(0,0,0,0.25), rgba(0,0,0,0.25)), url(${homepage.promoBanner.backgroundImage.url})`}}>
        <h2 className="font-extrabold text-4xl">{homepage.promoBanner.heading}</h2>
        <p>{homepage.promoBanner.subHeading}</p>
      </div>

      <h2 className="font-semibold text-2xl text-center mt-16">Products you might like</h2>

      <div className="grid sm:grid-cols-3 gap-6 mt-8">
        {homepage.featuredProducts.items.map(product => (
          <div key={product.id}>
            <Link href={`/products/${product.slug}`}>
              <a><img src={product.image.url} alt={`${product.name} Thumbnail`} /></a>
            </Link>
            <div className="flex flex-col">
              <div className="flex items-center justify-between mt-3 mb-2">
                <h4 className="font-medium">{product.name}</h4>
                ${product.price}
              </div>
              <p className="text-gray-500">{product.description}</p>
              <button type="button"
                      className="h-11 bg-gray-900 hover:bg-gray-800 text-white uppercase text-xs tracking-wide font-bold rounded mt-4 transition-colors duration-150 ease-in-out">
                Add to basket
              </button>
            </div>
          </div>
        ))}
      </div>
    </Layout>
  )
}

export async function getServerSideProps() {
  // Define homepage query
  const homepageQuery = `{
    homepageCollection(limit: 1) {
      items {
        promoBanner {
          heading
          subHeading
          backgroundImage {
            url
          }
        }
        featuredProducts {
          items {
            id
            slug
            name
            price
            description
            image {
              url
            }
          }
        }
      }
    }
  }`;
  // Fetch homepage content
  const result = await request({ query: homepageQuery });
  // Return
  return {
    props: {
      homepage: result.homepageCollection.items[0]
    }
  };
}

By exporting the getServerSideProps function, we’re telling Next.js that we would like this page to be rendered on the server as opposed to being statically generated.

After saving your changes, restart your development server, and the homepage of your project should look something like this:

Step 6: Create a product page

Next up, we’re going to create a product page. Since product pages are not typically personalized, we can statically generate them to improve performance.

Create a new file called pages/products/[slug].js and paste in the following contents:

import Layout from '../../components/layout';
import { request } from '../../lib/lexascms';

export default function Product({ product }) {
  return (
    <Layout>
      <div className="grid sm:grid-cols-2 gap-6">
        <img src={product.image.url} alt={`${product.name} Image`} />
        <div>
          <h1 className="font-medium text-2xl">{product.name}</h1>
          <div className="font-medium text-xl text-gray-600 my-2">
            ${product.price}
          </div>
          <p className="text-gray-500">{product.description}</p>
          <button type="button"
                  className="w-full h-11 bg-gray-900 hover:bg-gray-800 text-white uppercase text-xs tracking-wide font-bold rounded mt-4 transition-colors duration-150 ease-in-out">
            Add to basket
          </button>
        </div>
      </div>
    </Layout>
  )
}

export async function getStaticPaths() {
  // Define product slugs query
  const productSlugsQuery = `{
    productCollection {
      items {
        slug
      }
    }
  }`;
  // Fetch product slugs
  const productSlugs = await request({ query: productSlugsQuery });
  // Return
  return {
    paths: productSlugs.productCollection.items.map(product => ({
      params: {
        slug: product.slug
      }
    })),
    fallback: false
  };
}

export async function getStaticProps({ params }) {
  // Define product query
  const productQuery = `{
    productCollection(filter: { slug: { _eq: "${params.slug}" } }) {
      items {
        id
        slug
        name
        price
        description
        image {
          url
        }
      }
    }
  }`;
  // Fetch product data
  const product = await request({ query: productQuery });
  // Return
  return {
    props: {
      product: product.productCollection.items[0]
    }
  };
}

This time we’re exporting the getStaticPaths and getStaticProps functions, which tells Next.js that we want this route to be statically generated.

After saving your changes again, go back to your browser and click on one of the product thumbnails to open the product page.

Depending on which product you selected, you should see something like this:

Step 7: Implement personalization in the headless CMS

Now that you have a basic e-commerce store, we’re going to personalize the homepage!

To keep things simple, we’ll base the personalization on the value of a query parameter. However, in a real-world project, you would likely base it on data from a more realistic source such as profile information, order history, or even data fetched from third-party APIs.

When using LexasCMS, personalization is handled entirely by its Content Delivery API. This keeps your application code simple and ensures that content teams are free to experiment without the need for developers to make code changes.

As a simple example, we’re going to adjust the homepage banner and its featured products based on the visitor’s local temperature.

Step 7.1: Create an Audience Attribute

Audience attributes are the characteristics that are used to segment your visitors into any of your defined audiences.

Head back into LexasCMS and navigate to the Audiences > Attributes section. Once there, click on the Create Attribute button and create an attribute with the following values.

Name: Local Temperature
Key: localTemperature
Type: Number

Step 7.2: Create an Audience

Audiences allow you to segment visitors based on custom rules and conditions which you define. The rules and conditions themselves are defined using audience attributes.

We’re going to create a new audience that will only include visitors whose local temperature is greater than 20°C.

Navigate to the Audiences > Audiences section and then click on the Create Audience button. Create an audience with the following values:

Name: Warm Climate
Key: warmClimate

Step 7.3: Configure your Audience’s conditions

After creating your audience, you’ll be taken to the Edit Audience screen. This is where you define the rules and conditions which determine whether or not a visitor should be included within this audience.

Add an Attribute condition by clicking the Add Condition button.

Once the condition has been added, select the Local Temperature attribute which you created earlier, change the comparator to Greater Than, and enter 20 in the Value field.

Click the Save Changes button, and your audience should now look something like this:

Step 7.4: Target your new audience with a variation

Navigate to the Content section and locate the existing content item named Homepage.

Within the item, you’ll notice that there are two variations. One of which is currently a draft named Warm Climate and the other named Default, which is already published.

Default is the variation that is currently being displayed in your project
Warm Climate is the variation we’re going to target members of our newly created audience

Click on the Warm Climate variation to open it, and then look in the sidebar on the right of the screen for an Audience heading. This tells you which audience the variation is currently assigned to. Since one is yet to be assigned, there will be an Add Audience link instead.

Click the Add Audience link to reveal the Update Audience modal and then select the Warm Climate audience which you created earlier.

Click the Confirm button to apply your selection.

Once a variation has been assigned to an audience, it will only be delivered to visitors whose characteristics match the defined rules and conditions for the assigned audience.

Step 7.7: Publish your new variation

Now that your audience has been assigned to the variation enable the Published toggle and click the Save Changes button.

Step 7.8: Personalize your homepage

In your code editor, open your pages/index.js file and update the getServerSideProps function declaration to include { query } as the first argument.

Your function blueprint should then look something like this:

export async function getServerSideProps({ query }) {
  // ...
}

Next, find the call to request within your getServerSideProps function, and update it to look like this:

export async function getServerSideProps({ query }) {

  // ...

  // Define request context
  let requestContext = {
    audienceAttributes: {
      localTemperature: query.localTemp !== undefined ? parseInt(query.localTemp, 10) : null
    }
  };
  // Fetch homepage content
  const result = await request({
    query: homepageQuery,
    requestContext
  });

  // ...

}

This takes the localTemp query parameter value and passes it as the value for your localTemperature audience attribute. The audience attributes are then sent with your query to LexasCMS’s Content Delivery API, which uses the information to determine which variations of your content should be returned.

Notice how we haven’t touched the query itself or made any changes to our templates? This is exactly what makes LexasCMS’s personalization feature, so simple to integrate and maintain since all of the heavy lifting is handled by its Content Delivery API.

Save your changes. It’s now time to see the magic happen. ✨

Go back to your browser and reload your project's homepage (http://localhost:3000/).

You should see that nothing has changed and that it looks exactly the same as it did before. This is because we haven’t provided the localTemp query parameter.

Try reloading the homepage again, but this time add the localTemp query parameter with a value which is greater than 20 (e.g. http://localhost:3000/?localTemp=25).

This time, you should notice that your homepage has changed and that it’s now displaying the content from the Warm Climate variation.

Congratulations! You just personalized your first website page using LexasCMS. 🎉

Step 8: Implement Snipcart

What good is an e-commerce website if you can’t buy anything? Fortunately, Snipcart makes it amazingly simple to turn our website into a fully functioning e-commerce store!

Start by creating a new file named pages/_document.js and paste in the below contents, be sure to replace SNIPCART_API_KEY with your Snipcart’s API Key.

import Document, { Html, Head, Main, NextScript } from 'next/document'

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head>
          <link rel="preconnect" href="https://app.snipcart.com" />
          <link rel="preconnect" href="https://cdn.snipcart.com" />
          <link rel="stylesheet" href="https://cdn.snipcart.com/themes/v3.0.27/default/snipcart.css" />
        </Head>
        <body>
          <Main />

          <script async src="https://cdn.snipcart.com/themes/v3.0.27/default/snipcart.js"></script>
          <div hidden id="snipcart" data-api-key="SNIPCART_API_KEY"></div>
          <NextScript />
        </body>
      </Html>
    )
  }
}

export default MyDocument

This includes some external styles and scripts which Snipcart requires.

Next, open the pages/index.js file and locate the Add to Basket button within the template. Update the button so that it looks the same as the snippet below:

<button type="button"
        className="snipcart-add-item h-11 bg-gray-900 hover:bg-gray-800 text-white uppercase text-xs tracking-wide font-bold rounded mt-4 transition-colors duration-150 ease-in-out"
        data-item-id={product.id}
        data-item-price={product.price}
        data-item-url={`/products/${product.slug}`}
        data-item-description={product.description}
        data-item-image={product.image.url}
        data-item-name={product.name}>
  Add to basket
</button>

Notice that we’ve added a snipcart-add-item class and a few data attributes. Snipcart uses them to describe the product and determine its price.

Make the same changes to the Add to Basket button on your product page.

Restart your development server and then reload your project to find that the Add to Basket buttons are now functional!

Congratulations again! You now have a fully functioning and personalized e-commerce store. 🎉

Bonus: Setup visual previews

While not strictly required, being able to preview your website through your visitors' eyes is a powerful capability for content editors to wield.

Fortunately, LexasCMS’s visual preview feature provides this ability while also being pretty simple to implement.

Start by heading back into LexasCMS and navigating to the Settings > Previews section of your space.

Click the Create Preview button and create a new preview with the following attributes:

Name: Local Development
Preview URL: http://localhost:3000

After you’ve created the preview, navigate to Settings > API Keys and click the Create an API Key button.

Create a new API key named Local Development, being sure to enable the Content Delivery API (Preview) permission.

After the API Key has been created, copy the generated token as you’ll need it in the next step.

Open the lib/lexascms.js file in your code editor and replace the value of the apiKey variable with your newly generated API Key. Like with the space ID, you would likely pull your API Key from a pre-configured environment variable in a real-world project.

Next, open the pages/_document.js file and paste the below snippet before the closing body tag.

<script type="text/javascript" defer dangerouslySetInnerHTML={{ __html: `(function(e,t){void 0!==e.addEventListener&&e.addEventListener("load",function(){var e=t.getElementsByTagName("script")[0],n=t.createElement("script")
          n.type="text/javascript",n.async=!0,n.src="https://static.lexascms.com/lexascms.js",e.parentNode.insertBefore(n,e)},!1)})(window,document)` }} />

This script allows your project to communicate with LexasCMS’s visual preview tool.

When LexasCMS loads your project within its preview tool, it provides a pre-configured request context via the lexascmsRequestContext query parameter. When this query parameter is present, you should pass its value as the request context for all requests to LexasCMS instead of building your own.

To do this, open your pages/index.js file and locate the definition of the requestContext variable within your getServerSideProps function. Replace it with the following:

export async function getServerSideProps({ query }) {

  // ...

  // Define request context
  let requestContext;
  if (query.lexascmsRequestContext !== undefined) {
    requestContext = query.lexascmsRequestContext;
  } else {
    requestContext = {
      audienceAttributes: {
        localTemperature: query.localTemp !== undefined ? parseInt(query.localTemp, 10) : null
      }
    };
  }

  // ...

}

This change will check for the existence of the lexascmsRequestContext query parameter before attempting to build its own request context.

Restart your development server, and head back into LexasCMS.

After navigating to the Content Preview section of your space, you should see your project appear within the preview window.

The sidebar to the right provides controls that allow you to modify the context of the preview. Let’s set the value for our Local Temperature audience attribute and see what happens.

Click the Update link next to the Audience Attributes heading to reveal the Update Audience Attributes modal.

Using the Add Attribute button in the model, add the Local Temperature attribute and set its value to 25 (or anything greater than 20).

Click the Confirm button, followed by the Update Preview button in the sidebar to apply your changes.

You should see your project reload with the configured context and that the content from the Warm Climate variation is now being displayed. 🎉

Live Demo and GitHub repo

You can find a live demo of this tutorial as well as its source code using the links below:

Live Demo
Source Code

Closing thoughts

Personalization is already a big part of the e-commerce industry, and its importance is only going to grow as time moves on.

Hopefully, this post has shown you that by using LexasCMS, you can easily create personalized websites. Websites that allow content editors to experiment freely and simplify build and maintenance for developers.

We’re only just getting started with our plans for LexasCMS, and we have tons of exciting ideas which we can’t wait to share.

To keep up with LexasCMS’s latest updates, follow us on Twitter.

Want to learn more about LexasCMS? Try it for free by creating an account and starting your trial today.

Any questions or feedback? Tweet at us or email us to let us know!