Blog posts by Szymon Uryga2025-07-15T14:17:08.0000000Zhttps://world.optimizely.com/blogs/szymon-uryga/Optimizely WorldOptimizely Frontend Hosting: Deploy Without PowerShell Using the @kunalshetye/opticloud Package<p>In my last two blog posts, I walked through how to get started with deploying a <strong>headless app to Optimizely Frontend Hosting</strong> using PowerShell and the <strong>EpiCloud </strong>module. I also demonstrated how to <strong>automate the deployment</strong> using a script or GitHub Actions.</p>
<p>While that approach works great, it can be overwhelming for developers who aren’t familiar with <strong>PowerShell</strong> or the <a href="https://docs.developers.optimizely.com/digital-experience-platform/docs/deployment-api"><strong>Optimizely Deployment API</strong></a>. Fortunately, there's now a much easier way to get started - <strong>with a single command</strong> and <strong>no PowerShell knowledge required</strong>.</p>
<p>Enter <a href="https://www.npmjs.com/package/@kunalshetye/opticloud"><strong>@kunalshetye/opticloud</strong></a> - a fantastic NPM package built by <strong>Kunal Shetye</strong> that takes care of the entire deployment logic for you. I’ve recently started using it myself, and I was immediately impressed by how fast and simple it is. If you're a frontend developer deploying to Optimizely DXP for the first time, this tool should absolutely be your first choice.</p>
<p>In this article, I’ll show you how easy it is to deploy a headless app using this modern CLI.</p>
<p> </p>
<hr />
<h2> </h2>
<h2><strong>Deployment Without PowerShell - The @kunalshetye/opticloud NPM Package</strong></h2>
<p>For many developers, the first contact with Optimizely happens through the <strong>SaaS CMS</strong>, and they often have <strong>no experience with Optimizely DXP</strong> or PowerShell-based deployments. In these cases, the <strong> <a href="https://www.npmjs.com/package/@kunalshetye/opticloud">@kunalshetye/opticloud</a></strong> package is an <strong>excellent solution</strong>.</p>
<p>This modern CLI tool, created by <strong>Kunal</strong>, handles the entire deployment process in a simple and developer-friendly way - whether you're deploying a headless app, CMS or commerce project.</p>
<p> </p>
<hr />
<h3> </h3>
<h3><strong>🚀 How to Deploy Using the Optimizely DXP CLI</strong></h3>
<h4>1. Install the Package</h4>
<pre class="language-csharp"><code>npm install -g @kunalshetye/opticloud</code></pre>
<h4>2. Authenticate with DXP</h4>
<pre class="language-csharp"><code>opticloud auth:login</code></pre>
<p>You’ll be prompted to enter:</p>
<ul>
<li>
<p><strong>Client Key</strong> (from the DXP Cloud portal)</p>
</li>
<li>
<p><strong>Client Secret</strong></p>
</li>
<li>
<p><strong>Project ID</strong> (the GUID of your DXP project)</p>
</li>
</ul>
<h4>3. Use the ship Command</h4>
<p>Once authenticated, you can deploy your app using a single command:</p>
<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary">
<div class="overflow-y-auto p-4">
<pre class="language-csharp"><code>opticloud ship ./ \
--target=test1 \
--type=head \
--prefix=optimizely-one \
--version=1.0.0 \
--output=./
</code></pre>
</div>
</div>
<p>The <strong>ship </strong>command is the ultimate streamlined solution for Optimizely DXP deployments. It orchestrates everything from packaging to deployment in one step.</p>
<h4>4. Automate It with GitHub Actions</h4>
<p>Even better, <strong>opticloud </strong>comes with built-in support for <strong>GitHub Actions</strong>, making it easy to set up continuous deployment pipelines.</p>
<p>👉 Check out the official GitHub Actions documentation here: <a class="" href="https://github.com/kunalshetye/opticloud/blob/main/docs/github-actions.md"><strong>GitHub Actions Docs</strong></a></p>
<p> </p>
<hr />
<h2> </h2>
<h2><strong>🔚 Summary</strong></h2>
<p>Kunal has done an outstanding job building a <strong>modern deployment tool</strong> that eliminates the complexity of PowerShell and the legacy <strong>EpiCloud </strong>module. It’s now easier than ever for developers - especially frontend engineers who are new to Optimizely - to deploy to DXP with confidence.</p>
<p>With <strong>opticloud</strong>, you can:</p>
<ul>
<li>
<p>Deploy <strong>headless apps</strong>, CMS sites, commerce platforms, and even SQL databases</p>
</li>
<li>
<p>Use <strong>GitHub Actions</strong> for seamless CI/CD</p>
</li>
<li>
<p>Avoid the <strong>steep learning curve</strong> of traditional DXP tooling</p>
</li>
</ul>
<p>📘 Highly recommended: Explore the full documentation here → <a class="" href="https://www.npmjs.com/package/@kunalshetye/opticloud"><strong>opticloud on NPM</strong></a></p>
<p> </p>2025-07-15T14:17:08.0000000ZBlog postHow to Set Up CI/CD Pipeline for Optimizely Frontend Hosting Using GitHub Actions<p>As I promised in my <a class="" href="/link/ae36e13df40b4bc6849c621eda993915.aspx">previous blog post</a> about getting started with Optimizely Frontend Hosting, today I’m delivering on that promise by sharing how to automate your deployment process with <strong>GitHub Actions</strong>. In this step-by-step tutorial, I’ll show you how to set up a CI/CD pipeline that automatically deploys your frontend app every time you push to the <strong>main </strong>branch.</p>
<h2>Prerequisites</h2>
<p>Before you start, make sure you have:</p>
<ul>
<li>
<p>A working Optimizely Frontend Hosting setup (with environments like <em>Test1</em>, <em>Test2</em>, <em>Production1</em>)</p>
<ul>
<li>Remember to <strong>add all </strong>necessary env variable <strong>before </strong>you do deployemnt</li>
</ul>
</li>
<li>
<p>Your Optimizely <strong>Project ID</strong>, <strong>Client Key</strong>, and <strong>Client Secret</strong></p>
</li>
<li>
<p>A PowerShell deployment script (see below)</p>
</li>
<li>
<p>A GitHub repo with your project code</p>
</li>
</ul>
<h2> </h2>
<h2>Step 1: Add Secrets to GitHub</h2>
<p>Go to your GitHub repository → <strong>Settings</strong> → <strong>Secrets and variables</strong> → <strong>Actions</strong> → click <strong>New repository secret</strong>:</p>
<table style="border-collapse: collapse; border-spacing: 2px; margin-left: 0px; margin-right: auto; border: 2px solid rgb(0, 0, 0);">
<thead>
<tr>
<th style="border-width: 2px; padding: 2px; border-color: rgb(0, 0, 0);">Name</th>
<th style="border-width: 2px; padding: 2px; border-color: rgb(0, 0, 0);">Value</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-width: 2px; padding: 2px; border-color: rgb(0, 0, 0);">OPTI_PROJECT_ID</td>
<td style="border-width: 2px; padding: 2px; border-color: rgb(0, 0, 0);">Your Optimizely Project ID</td>
</tr>
<tr>
<td style="border-width: 2px; padding: 2px; border-color: rgb(0, 0, 0);">OPTI_CLIENT_KEY</td>
<td style="border-width: 2px; padding: 2px; border-color: rgb(0, 0, 0);">Your Optimizely Client Key</td>
</tr>
<tr>
<td style="border-width: 2px; padding: 2px; border-color: rgb(0, 0, 0);">OPTI_CLIENT_SECRET</td>
<td style="border-width: 2px; padding: 2px; border-color: rgb(0, 0, 0);">Your Optimizely Client Secret</td>
</tr>
</tbody>
</table>
<h2> </h2>
<h2>Step 2: Prepare the PowerShell Deployment Script</h2>
<p>Create a script called <strong>deploy.ps1</strong> in your repo (e.g., under a <strong>scripts/</strong> folder).</p>
<pre class="language-csharp"><code># scripts/deploy.ps1
# Validate required environment variables
if (-not $env:OPTI_PROJECT_ID -or -not $env:OPTI_CLIENT_KEY -or -not $env:OPTI_CLIENT_SECRET) {
Write-Host "Missing required environment variables." -ForegroundColor Red
exit 1
}
# Install and import EpiCloud module
Install-Module -Name EpiCloud -Scope CurrentUser -Force -ErrorAction SilentlyContinue
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
Import-Module EpiCloud
# Deployment settings
$projectId = $env:OPTI_PROJECT_ID
$clientKey = $env:OPTI_CLIENT_KEY
$clientSecret = $env:OPTI_CLIENT_SECRET
$targetEnvironment = "Test1"
# Paths
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
$zipName = "optimizely-one-github.head.app.$timestamp.zip"
$zipPath = ".\$zipName"
# Create ZIP from current directory excluding ignored files
# (GitHub Actions runners will not include `.git`, so you're safe)
Compress-Archive -Path * -DestinationPath $zipPath
if (-not (Test-Path $zipPath)) {
Write-Host "Failed to create ZIP file." -ForegroundColor Red
exit 1
}
# Deploy using EpiCloud
Connect-EpiCloud -ProjectId $projectId -ClientKey $clientKey -ClientSecret $clientSecret
$sasUrl = Get-EpiDeploymentPackageLocation
Add-EpiDeploymentPackage -SasUrl $sasUrl -Path $zipPath
Start-EpiDeployment `
-DeploymentPackage $zipName `
-TargetEnvironment $targetEnvironment `
-Wait
</code></pre>
<p>This script will:</p>
<ul>
<li>
<p>Zip everything in the repo</p>
</li>
<li>
<p>Authenticate to Optimizely</p>
</li>
<li>
<p>Upload and deploy the package to the selected environment</p>
</li>
</ul>
<p> </p>
<h2>Step 3: Create GitHub Action Workflow</h2>
<p>Create a file at <strong>.github/workflows/deploy.yml </strong>in your repository:</p>
<pre class="language-csharp"><code>name: Deploy to Optimizely
on:
push:
branches:
- main
jobs:
deploy:
runs-on: windows-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Setup PowerShell
shell: pwsh
run: |
Write-Host "PowerShell ready"
- name: Run deployment script
shell: pwsh
run: ./scripts/deploy.ps1
env:
OPTI_PROJECT_ID: ${{ secrets.OPTI_PROJECT_ID }}
OPTI_CLIENT_KEY: ${{ secrets.OPTI_CLIENT_KEY }}
OPTI_CLIENT_SECRET: ${{ secrets.OPTI_CLIENT_SECRET }}
</code></pre>
<h2>Step 4: Test It</h2>
<ol>
<li>
<p>Commit your <strong>deploy.ps1</strong> and workflow to the repository.</p>
</li>
<li>
<p>Push to <strong>main</strong>.</p>
</li>
<li>
<p>Go to <strong>GitHub → Actions</strong> and check if the deployment workflow ran successfully.</p>
</li>
<li>
<p>Check the <strong>Optimizely DXP Portal</strong> to confirm the deployment on the <em>Test1 </em>environment.</p>
</li>
</ol>
<p> </p>
<h2>Result</h2>
<p>Here are two screenshots showing the final result:</p>
<h3>GitHub Actions</h3>
<p><img src="/link/0cdbf2cf6ee2458d98ef66966f9c1811.aspx" /></p>
<p>The workflow completed successfully with detailed logs from the PowerShell deployment.</p>
<h3>Optimizely PaaS Portal</h3>
<p><img src="/link/46f44cbda765465d8cffba607540c6d3.aspx" /></p>
<p>You can see the package <strong>optimizely-one-github.head.app.20250702-102756.zip</strong> was successfully deployed to the <strong>Test1 </strong>environment.</p>
<h2>Conclusion</h2>
<p>With just a few steps, you’ve automated your frontend deployments to Optimizely using GitHub Actions. This approach ensures that your latest changes in <strong>main </strong>are always deployed to your specifed environment, improving developer velocity and reducing manual errors.</p>2025-07-02T11:52:03.0000000ZBlog postDeploying to Optimizely Frontend Hosting: A Practical Guide<p><strong>Optimizely Frontend Hosting</strong> is a cloud-based solution for deploying headless frontend applications - currently supporting only <strong>Next.js</strong> projects. Its deployment process and core concept are familiar to .NET developers who have worked with <strong>Optimizely DXP</strong>: code is deployed via a managed pipeline, and environment setup is handled entirely by Optimizely.</p>
<p>Out of the box, Optimizely Frontend Hosting includes a <strong>Web Application Firewall (WAF)</strong> and <strong>CDN</strong> powered by <strong>Cloudflare</strong>, ensuring your statically generated Next.js content is delivered globally with high performance and security - no additional configuration required.</p>
<p><img src="/link/0f792590380345c69f54d59c0630e09c.aspx" /></p>
<p> </p>
<h3><strong>Key Characteristics</strong></h3>
<ul>
<li>
<p><strong>Next.js support only</strong> (as of now)</p>
</li>
<li>
<p><strong>Managed environments</strong> like Test1, Test2 and Production for SaaS CMS </p>
</li>
<li>
<p><strong>Automatic CDN and WAF configuration</strong></p>
</li>
<li>
<p><strong>Static site hosting</strong></p>
</li>
</ul>
<p>It’s worth noting that customization capabilities are currently limited. For advanced features or custom configuration (e.g., setting cache headers, redirects, custom domains, etc.), it’s recommended to contact <strong>Optimizely Support</strong>.</p>
<p>Compared to frontend-specialized platforms like Vercel, Optimizely Frontend Hosting doesn’t aim to deliver a full-featured developer platform. Instead, it offers a <strong>stable and integrated solution</strong> for teams already working with the Optimizely stack, looking for a <strong>reliable and supported way to host frontend applications</strong> alongside their CMS and backend infrastructure.</p>
<p>This makes it ideal for enterprise use cases where <strong>vendor consolidation</strong>, <strong>support unification</strong>, and <strong>environment control</strong> are priorities.<br /><br /></p>
<h2><strong>🚀 Deployment in Practice</strong></h2>
<p>Here’s how a typical deployment looks:</p>
<h3><strong>Step-by-step manual deployment (recommended to start with):</strong></h3>
<ol>
<li>
<p><strong>Open PowerShell</strong></p>
</li>
<li>
<p><strong>Install and import the EpiCloud module:<br /></strong></p>
<pre class="language-csharp"><code>Install-Module -Name EpiCloud -Scope CurrentUser -Force
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Import-Module EpiCloud
</code></pre>
</li>
<li>
<p><strong>Set credentials and environment:<br /></strong></p>
<pre class="language-csharp"><code>$projectId = "<your_project_id>"
$clientKey = "<your_client_key>"
$clientSecret = "<your_client_secret>"
$targetEnvironment = "Test1" # Or "Production" Or "Test2"</code></pre>
</li>
<li>
<p><strong>Zip your Next.js application<br /></strong>Name format:</p>
<pre class="language-csharp"><code><name>.head.app.<version>.zip</code></pre>
<p>Example: <code>optimizely-one.head.app.20250610.zip</code></p>
<blockquote>
<p>⚠️ If .<strong>head.app.</strong> is not in the filename, the deployment system will treat it as a .NET NuGet package instead.</p>
</blockquote>
</li>
<li>
<p><strong>Connect to EpiCloud and get the SAS URL:<br /></strong></p>
<pre class="language-csharp"><code>Connect-EpiCloud -ProjectId $projectId -ClientKey $clientKey -ClientSecret $clientSecret
$sasUrl = Get-EpiDeploymentPackageLocation
</code></pre>
</li>
<li>
<p><strong>Upload your deployment package:<br /></strong></p>
<pre class="language-csharp"><code>Add-EpiDeploymentPackage -SasUrl $sasUrl -Path .\optimizely-one.head.app.20250610.zip
</code></pre>
</li>
<li>
<p><strong>Trigger deployment:<br /></strong></p>
<pre class="language-csharp"><code>Start-EpiDeployment `
-DeploymentPackage "optimizely-one.head.app.20250610.zip" `
-TargetEnvironment $targetEnvironment `
-DirectDeploy `
-Wait `
-Verbose
</code></pre>
</li>
</ol>
<h2><strong>Automating Deployment</strong></h2>
<p>Once you understand the manual steps, you can fully automate the deployment process using a PowerShell script like the one below. This approach ensures repeatability and helps integrate deployment into your CI/CD pipeline.</p>
<blockquote>
<p>💡 It’s <strong>highly recommended to perform a few deployments manually</strong> before automating, to build confidence and understanding. This will help later when diagnosing issues or customizing the flow.</p>
</blockquote>
<h2><strong>1. .zipignore Support</strong></h2>
<p>To avoid bundling unnecessary files into your deployment zip package, the script supports a .<strong>zipignore </strong>file (similar to <strong>.gitignore</strong>). Place this file in your app’s root directory (<strong>$sourcePath</strong>) and list the paths or folders to <strong>exclude</strong> from the archive.</p>
<h3><strong>Example .zipignore:</strong></h3>
<pre class="language-csharp"><code>.next
node_modules
.env
.git
.DS_Store
.vscode
</code></pre>
<blockquote>
<p>⚠️ If no files remain after filtering with <strong>.zipignore</strong>, the script will exit with an error.</p>
</blockquote>
<h3><strong>2. How to Customize the Script for Your Project</strong></h3>
<p>You need to adjust <strong>two key values</strong> in the script:</p>
<ol>
<li>
<p><strong>Path to your Next.js app:<br /></strong></p>
<pre class="language-csharp"><code>$sourcePath = "C:\Workspace\Personal\optimizely-one"
</code></pre>
<p>Replace this with the actual path to your project.</p>
</li>
<li>
<p><strong>Target deployment environment:<br /></strong></p>
<pre class="language-csharp"><code>$targetEnvironment = "Test1"</code></pre>
<p>Set the <strong>$targetEnvironment</strong> variable to match the environment configured in your Optimizely project.</p>
<ul>
<li>
<p><strong>For SaaS Frontend Hosting:</strong> use one of the predefined environment names, such as: "Test1", "Test2", or "Production"</p>
</li>
<li>
<p><strong>For traditional PaaS hosting:</strong> use one of the standard Optimizely environment names: "Integration", "Preproduction", or "Production"</p>
</li>
</ul>
<p>Make sure the name you use matches exactly what is defined in the Optimizely project portal.</p>
</li>
</ol>
<h3><strong>3. Required Environment Variables</strong></h3>
<p>Before running the script, you need to define the following <strong>environment variables</strong>:</p>
<ul>
<li>OPTI_PROJECT_ID</li>
<li>OPTI_CLIENT_KEY</li>
<li>OPTI_CLIENT_SECRET</li>
</ul>
<p>You can find these in the <strong>API section</strong> of the <a class="cursor-pointer" href="">Optimizely PaaS Portal</a> for your frontend project.</p>
<p><br /><img src="/link/b82a89e84c934d06abef2cb3aa64c71a.aspx" /></p>
<p> </p>
<h4><strong>To set them temporarily in PowerShell:</strong></h4>
<pre class="language-csharp"><code>$env:OPTI_PROJECT_ID = "<your_project_id>"
$env:OPTI_CLIENT_KEY = "<your_client_key>"
$env:OPTI_CLIENT_SECRET = "<your_client_secret>"
</code></pre>
<blockquote>
<p>📝 Alternatively, you can add them permanently to your system environment variables.</p>
</blockquote>
<h3>4. How to Run the Script</h3>
<ol>
<li>
<p>Open <strong>PowerShell.</strong></p>
</li>
<li>
<p>Save the script below to a <strong>.ps1 </strong>file, e.g. <strong>deploy-optimizely.ps1</strong></p>
</li>
<li>
<p>Set the required environment variables (see above).</p>
</li>
<li>
<p>Run the script:</p>
<pre class="language-csharp"><code>.\deploy-optimizely.ps1</code></pre>
</li>
</ol>
<p> </p>
<h3><strong>5. PowerShell Deployment Script (with Comments)</strong></h3>
<pre class="language-csharp"><code># Check required environment variables
if (-not $env:OPTI_PROJECT_ID -or -not $env:OPTI_CLIENT_KEY -or -not $env:OPTI_CLIENT_SECRET) {
Write-Host "Missing one or more required environment variables: OPTI_PROJECT_ID, OPTI_CLIENT_KEY, OPTI_CLIENT_SECRET" -ForegroundColor Red
exit 1
}
# Install and import EpiCloud module
Install-Module -Name EpiCloud -Scope CurrentUser -Force -ErrorAction SilentlyContinue
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
Import-Module EpiCloud
# Settings
$projectId = $env:OPTI_PROJECT_ID
$clientKey = $env:OPTI_CLIENT_KEY
$clientSecret = $env:OPTI_CLIENT_SECRET
$targetEnvironment = "Test1" # Change to Production, Test2, etc. as needed
# Path to the root of your Next.js app
$sourcePath = "C:\Workspace\Personal\optimizely-one" # <- CHANGE THIS
# Generate unique zip filename
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
$zipName = "optimizely-one.head.app.$timestamp.zip"
$zipPath = ".\$zipName"
# Remove existing archive if present
if (Test-Path $zipPath) { Remove-Item $zipPath }
# Load .zipignore file if it exists
$zipIgnorePath = Join-Path $sourcePath ".zipignore"
$excludeRoot = @()
if (Test-Path $zipIgnorePath) {
$excludeRoot = Get-Content $zipIgnorePath | Where-Object { $_ -and $_ -notmatch "^#" }
}
$rootExcludes = $excludeRoot | ForEach-Object { Join-Path $sourcePath $_ }
# Collect files excluding those in .zipignore
$includeFiles = Get-ChildItem -Path $sourcePath -Recurse -File | Where-Object {
foreach ($ex in $rootExcludes) {
if ($_.FullName -like "$ex\*" -or $_.FullName -eq $ex) {
return $false
}
}
return $true
}
if ($includeFiles.Count -eq 0) {
Write-Host "ERROR: No files to archive after applying .zipignore filters." -ForegroundColor Red
exit 1
}
# Prepare temporary folder for zipping
$tempPath = Join-Path $env:TEMP "nextjs-build-zip"
if (Test-Path $tempPath) { Remove-Item -Recurse -Force $tempPath }
New-Item -ItemType Directory -Path $tempPath | Out-Null
foreach ($file in $includeFiles) {
$relativePath = $file.FullName.Substring($sourcePath.Length).TrimStart('\')
$destPath = Join-Path $tempPath $relativePath
$destDir = Split-Path -Path $destPath -Parent
if (-not (Test-Path -LiteralPath $destDir)) {
New-Item -ItemType Directory -Path $destDir -Force | Out-Null
}
Copy-Item -LiteralPath $file.FullName -Destination $destPath -Force
}
# Create the ZIP archive
Compress-Archive -Path "$tempPath\*" -DestinationPath $zipPath
if (-not (Test-Path $zipPath)) {
Write-Host "ERROR: Failed to create ZIP file." -ForegroundColor Red
exit 1
}
Remove-Item -Recurse -Force $tempPath
# Authenticate and deploy
Connect-EpiCloud -ProjectId $projectId -ClientKey $clientKey -ClientSecret $clientSecret
$sasUrl = Get-EpiDeploymentPackageLocation
Add-EpiDeploymentPackage -SasUrl $sasUrl -Path $zipPath
Start-EpiDeployment `
-DeploymentPackage $zipName `
-TargetEnvironment $targetEnvironment `
-DirectDeploy `
-Wait `
-Verbose
</code></pre>
<h2> </h2>
<h2><strong>⚠️ Don’t Repeat My Mistakes</strong></h2>
<p>Based on my own experience, here are some common pitfalls to avoid when deploying your application to Optimizely Hosting:</p>
<ol>
<li>
<p><strong>Always set all environment variables in the PaaS Portal <em>before</em> starting the deployment.</strong><br />I’ve made the mistake of launching the deployment first and then realizing the environment variables were missing. This caused the production build to fail, as the deployment process triggers a production build command right away. Without access to required environment variables, the build will break, and the environment can remain locked for a while.<br />👉 <strong>Set the variables first, then deploy.</strong></p>
</li>
<li>
<p><strong>Avoid using “Send to ZIP” on Windows.</strong><br />This method wraps your files inside an additional folder, which causes the package to be invalid for Optimizely Hosting. The platform expects to find files like <strong>package.json</strong> at the root of the ZIP – it doesn’t dig deeper into nested folders.</p>
</li>
<li>
<p><strong>Make sure your ZIP includes all necessary files.</strong><br />When working with frameworks like Next.js, routing is often handled via special folder structures like route groups <strong>(draft)</strong> or dynamic routes <strong>article/[slug]</strong>. If you use an automation script, sometimes files like <strong>page.tsx</strong> don't get copied correctly. Double-check your ZIP content before uploading.</p>
</li>
<li>
<p><strong>Follow the required ZIP naming convention:</strong><br />Use the format: <strong><name>.head.app.<version>.zip</strong></p>
</li>
<li>
<p><strong>Don’t include node_modules or .next folders in your ZIP.</strong><br />These are unnecessary for the deployment and will significantly increase your file size, slowing down the upload process.</p>
</li>
</ol>
<h2><strong>Result: </strong></h2>
<p>After completing the above steps, the deployment process will begin. It usually takes just a few minutes to complete.</p>
<p>You can monitor the deployment status directly in the <strong>Optimizely admin panel</strong>, as shown in the screenshot below:</p>
<p>Once the deployment finishes successfully, your application will be live and ready to use. The status will indicate that the deployment was successful, confirming that everything went smoothly.</p>
<h2><br /><img src="/link/0c9445cabdbc4621948f095cad29195b.aspx" /></h2>
<h2> </h2>
<h2><strong>Coming Soon: GitHub CI/CD Integration</strong></h2>
<p>In the near future, I’ll publish a guide showing how to <strong>integrate this deployment flow with GitHub Actions</strong>, enabling automatic deployment to Optimizely Frontend Hosting on every merge to the <strong>main </strong>branch.</p>
<p>Stay tuned!</p>2025-06-25T12:49:54.0000000ZBlog postCommon Mistakes in Headless Projects with Optimizely<p>Adopting a headless architecture with Optimizely is a major shift from the traditional MVC-based development that has been the standard for years. While the flexibility and performance of headless setups are often worth the transition, many teams make avoidable mistakes during their first headless implementations. In this post, I’ll highlight some of the most common issues I’ve seen - and how to avoid them.</p>
<p> </p>
<h2>1. Overemphasis on PaaS vs. SaaS</h2>
<p>One of the first decisions teams face is whether to use Optimizely's PaaS (Platform as a Service) or SaaS (Software as a Service) version. Unfortunately, many technical teams get stuck in the weeds of this decision.</p>
<p><strong>The reality?</strong> From a headless application perspective, both versions ultimately store and serve content via <strong>Optimizely Graph</strong>. That’s what your frontend connects to. So the technical differences are minimal in the context of a headless frontend.</p>
<p><strong>What matters more</strong> is whether the SaaS version meets all your business and integration requirements. If you need heavy customizations, advanced workflows, or .NET-based extensions, then PaaS might be necessary. Otherwise, SaaS can offer faster onboarding, better scalability, and less maintenance.</p>
<p> </p>
<h2>2. Ignoring Auto-Generated Types from Optimizely Graph</h2>
<p>Optimizely Graph supports <strong>code generation (codegen)</strong>, which allows developers to generate strongly typed classes based on your content model.</p>
<p>Yet, in many projects, teams skip this and manually type out GraphQL queries and expect responses as raw JSON. This leads to:</p>
<ul>
<li>
<p>Guesswork about what fields are available</p>
</li>
<li>
<p>Increased chance of typos</p>
</li>
<li>
<p>Fragile code due to schema mismatches</p>
</li>
<li>
<p>Slower development and debugging<br /><br /></p>
</li>
</ul>
<p><strong>Recommendation: </strong>Use the codegen tools provided by Optimizely Graph to automatically generate TypeScript (or your preferred language) types. This gives developers instant access to the schema, autocomplete, and type checking — significantly reducing runtime bugs and increasing productivity.</p>
<p> </p>
<h2>3. Header and Footer Misplaced as Homepage Blocks</h2>
<p>A common anti-pattern in headless Optimizely projects is placing global components like the <strong>header and footer </strong>directly on the homepage as blocks. While it may seem convenient, it creates serious architectural problems.</p>
<p>Why it’s a problem:</p>
<ul>
<li>
<p>Webhooks only detect changes to the homepage, so <strong>header/footer changes won’t trigger cache invalidation</strong> unless the entire homepage is republished.</p>
</li>
<li>
<p>The frontend is forced to <strong>rebuild or refetch the entire homepage</strong>, even if only the footer changes.</p>
</li>
<li>
<p>It creates a tight coupling between unrelated content.<br /><br /></p>
</li>
</ul>
<p><strong>Recommendation: </strong>Treat the header and footer as <strong>independent content items</strong> in the CMS - for example, create two separate pages: <em>SiteHeader </em>and <em>SiteFooter</em>. This allows fine-grained cache invalidation, better content reuse, and simpler frontend logic.</p>
<h2>4. Exposing Internal CMS URLs</h2>
<p>Another common mistake is exposing <strong>internal CMS URLs </strong>(e.g., for images or links) directly in frontend code. This happens when frontend apps render URLs exactly as returned by Optimizely - which often point to internal environments or CMS instances.</p>
<p>This is both a <strong>security issue</strong> and a <strong>performance problem</strong>:</p>
<ul>
<li>
<p>URLs may break if environments change</p>
</li>
<li>
<p>Internal infrastructure is exposed to the public<br /><br /></p>
</li>
</ul>
<p><strong>Recommendation: </strong>Always serve media and links via a <strong>frontend-friendly abstraction layer</strong>. Ideally, images and files should be proxied through a CDN or asset management service. Any CMS-specific URLs should be sanitized or mapped before being passed to the client.</p>
<p> </p>
<h2>Final Thoughts</h2>
<p>Headless CMS development offers flexibility, scalability, and performance - but it comes with new patterns and pitfalls. Many of the issues listed here stem from applying traditional CMS thinking to a modern headless setup.</p>
<p>If you're starting a headless project with Optimizely, take time to:</p>
<ul>
<li>
<p>Think in terms of APIs, not pages.</p>
</li>
<li>
<p>Embrace tooling like GraphQL codegen.</p>
</li>
<li>
<p>Decouple global content from page-specific content.</p>
</li>
<li>
<p>Abstract all internal CMS data behind your frontend.<br /><br /></p>
</li>
</ul>
<p>By avoiding these common mistakes, you’ll not only improve the developer experience but also deliver faster, more maintainable digital experiences.</p>
<p> </p>2025-05-19T11:53:07.0000000ZBlog postAn Introduction to Composable Commerce Architecture with Optimizely <p>In today's fast-moving digital economy, businesses need flexibility, speed, and the ability to adapt their commerce ecosystems rapidly. Traditional monolithic platforms often struggle to keep pace with changing market demands and evolving customer expectations. This is where composable commerce architecture emerges as a game-changer.</p>
<p>As a professional specializing in modern commerce architectures, I've successfully delivered composable commerce solutions and conducted extensive research into optimizing these systems with various platforms. Recently, I've been particularly focused on exploring Optimizely's powerful capabilities in this space, developing several advanced demonstration implementations that showcase its potential. Through this work, I've gained valuable insights into architectural approaches that leverage Optimizely's strengths for composable commerce. Let me share what I've learned about building effective, enterprise-ready composable commerce solutions with Optimizely.</p>
<p>Let’s start with the basics.</p>
<h2><strong>What is Composable Commerce?</strong></h2>
<p>Composable commerce is all about building your ideal system by combining best-in-class services for each specific business need. Rather than relying on a single platform to handle everything, you select specialized tools - such as a CMS, product database, checkout system - and connect them through APIs.</p>
<p>The key principles behind composable commerce include:</p>
<ul>
<li>
<p><strong>Best-of-breed approach</strong>: Selecting the optimal services for each specific function instead of using a single all-in-one platform</p>
</li>
<li>
<p><strong>API-first connectivity</strong>: Connecting everything through APIs and utilizing headless frontends for maximum flexibility</p>
</li>
<li>
<p><strong>Business agility</strong>: Innovating faster, scaling easily, and avoiding vendor lock-in</p>
</li>
</ul>
<p>Simply put, composable commerce enables businesses to move faster, experiment with new ideas more easily, and remain adaptable to whatever the market demands.</p>
<h2><strong>How Optimizely Enables Composable Commerce</strong></h2>
<p>Optimizely plays a crucial role in building robust composable commerce solutions. Through its SaaS CMS and PaaS CMS, Optimizely Graph, and other services, it provides powerful tools for managing content, products, and transactional data in a flexible, scalable way.</p>
<p>Let's explore two different architectural approaches to implementing composable commerce with Optimizely. These examples differ primarily in whether the Optimizely Connect Platform is used as an integration hub, each with its own advantages and trade-offs.</p>
<p><strong> </strong></p>
<h2><strong>Traditional Composable Commerce (Without Optimizely Connect Platform)</strong></h2>
<p> <img src="/link/d861e4d7d0e04a0cbab92da4dc8ab438.aspx?1747646433342" width="1200" height="876" /><br /><br />This architecture represents a more traditional approach to composable commerce, where Optimizely SaaS CMS, Optimizely Graph, and transactional commerce services are integrated directly without a central integration hub. In this model, the headless application acts as the orchestrator that combines all services.</p>
<h3><strong>🟢 Product Information Management (PIM)</strong></h3>
<p>The PIM system enriches product data beyond what's typically supported by SaaS commerce providers, handling both core product data and extended attributes stored as metafields,for example including:</p>
<ul>
<li>
<p><strong>Subscription Flag</strong>: Determines if a product is eligible for subscription</p>
</li>
<li>
<p><strong>Default Variant SKU</strong>: Defines which variant should be preselected</p>
</li>
<li>
<p><strong>Group-Based Pricing</strong>: Stored as a JSON object for dynamic price rendering based on user groups</p>
</li>
<li>
<p><strong>Product Status</strong>: JSON field for availability (e.g., backorder, out of stock)</p>
</li>
<li>
<p><strong>Order Limits</strong>: Restrictions on how many items a customer can order within a specific timeframe</p>
</li>
</ul>
<p>All this enriched data is sent to the transactional commerce system and consumed by the frontend application.</p>
<h3><strong>🟠 Transactional Commerce Services</strong></h3>
<p>This layer manages all commerce operations including:</p>
<ul>
<li>
<p>Order Processing & Checkout</p>
</li>
<li>
<p>Inventory and Pricing</p>
</li>
<li>
<p>Customer Account Data</p>
</li>
<li>
<p>Payment Gateway Configuration</p>
</li>
<li>
<p>Promotions & Discount Logic</p>
</li>
<li>
<p>Marketing Automation (e.g., abandoned carts)</p>
</li>
<li>
<p>Category Management and Filtering</p>
</li>
</ul>
<p>It exposes APIs that allow the headless frontend to interact with real-time data for carts, customer orders, and stock availability.</p>
<h3><strong>🔵 Optimizely Graph</strong></h3>
<p>Optimizely Graph functions as a high-performance GraphQL content delivery platform, acting as a CDN-distributed index for all CMS content and localized product information (titles, descriptions, media, etc.).</p>
<p>It delivers:</p>
<ul>
<li>
<p>CMS Pages and Product Content Blocks</p>
</li>
<li>
<p>Localized translations</p>
</li>
<li>
<p>SEO metadata</p>
</li>
<li>
<p>Product descriptions and assets tied to SKU/product IDs</p>
</li>
</ul>
<p>All this data is accessible by the frontend using GraphQL, enabling dynamic and multilingual rendering.</p>
<h3><strong>🔵 Optimizely SaaS CMS</strong></h3>
<p>This is the content management service used by marketers and editors. It includes:</p>
<ul>
<li>
<p>A Visual Builder for assembling reusable content components</p>
</li>
<li>
<p>Content publishing workflows</p>
</li>
<li>
<p>Management of content blocks, pages, and translations</p>
</li>
</ul>
<p>All published content is indexed in Optimizely Graph for frontend consumption.</p>
<h3><strong>🟣 Headless Application</strong></h3>
<p>The headless frontend (built in a framework like Next.js) orchestrates data across services:</p>
<ul>
<li>
<p>Retrieves CMS pages and product content from Optimizely Graph</p>
</li>
<li>
<p>Fetches inventory, pricing, and promotion details from transactional commerce APIs</p>
</li>
<li>
<p>Manages cart and checkout flows using commerce services</p>
</li>
<li>
<p>Renders localized product detail pages by combining data from both CMS and transactional commerce systems</p>
</li>
</ul>
<p> </p>
<h4>Product Page Rendering:</h4>
<ul>
<li>
<p>Request commerce service for product data (SKU, price, inventory, status)</p>
</li>
<li>
<p>Use the SKU or product ID to query Optimizely Graph for multilingual CMS content (title, description, media)</p>
</li>
</ul>
<h4>Cart Rendering:</h4>
<ul>
<li>
<p>Dynamically loads product title, image, and description from Optimizely Graph using SKU or variant ID</p>
</li>
</ul>
<h4>Category Pages:</h4>
<ul>
<li>
<p>Retrieved from commerce backend, then enriched with CMS data (if available)</p>
</li>
</ul>
<h3> </h3>
<h3><strong>Integration Logic</strong></h3>
<ul>
<li>
<p><strong>PIM → Transactional Commerce</strong>: Sends core product data + metafields</p>
</li>
<li>
<p><strong>SaaS CMS → Optimizely Graph</strong>: Publishes content to the GraphQL index</p>
</li>
<li>
<p><strong>Frontend → Optimizely Graph</strong>: Loads CMS pages and multilingual product info</p>
</li>
<li>
<p><strong>Frontend → Commerce Services</strong>: Fetches real-time data like cart contents, prices, promotions, and inventory</p>
</li>
</ul>
<p>You can see an example implementation of this approach using Optimizely SaaS CMS with Shopify at<a href="https://optimizely-one-nu.vercel.app/"> https://optimizely-one-nu.vercel.app/</a></p>
<h2><strong>Composable Commerce with Optimizely Connect Platform </strong></h2>
<p>Now let's explore how the architecture changes when we leverage the Optimizely Connect Platform as a central integration hub.</p>
<h3><strong>What is the Optimizely Connect Platform (OCP)?</strong></h3>
<p>The Optimizely Connect Platform (OCP) empowers developers to streamline data ingestion and channel activation by creating connectors that integrate seamlessly with any marketing suite. Developers can publish these connectors to the App Directory, and marketers can easily install and use them to compose digital experiences. - <a href="/link/4ca2b24d63b344bc845aacd96cd88290.aspx">https://world.optimizely.com/products/ocp/overview/</a> </p>
<p>In essence, OCP allows you to create applications that take information from transactional commerce services and add it to Optimizely Graph. It serves as a hub that aggregates data from multiple sources into one cohesive system.</p>
<p>Let's move on to architecture where we will learn about the strength of the Optimizely Connect Platform</p>
<p><strong> </strong></p>
<p><img src="/link/692d1e0c3a0840fa9d57d5f8cf82b056.aspx?1747646410084" width="1200" height="476" /></p>
<p>This architecture leverages Application in Optimizely Connect Platform as a central integration hub between content and commerce systems.</p>
<h3><strong>🟣 PIM (Product Information Management)</strong></h3>
<p>The PIM system handles the same product data enrichment as in the previous architecture, managing attributes like subscription flags, default variant SKUs, group-based pricing, product status, and order limits.</p>
<h3><strong>🟠 Transactional Commerce Services</strong></h3>
<p>This layer handles all core commerce operations, including order processing, inventory management, checkout and payment gateways, customer data, marketing campaigns, and product categorization, filtering, and promotion logic.</p>
<h3><strong>🟣 Optimizely Connect Platform (Integration Hub)</strong></h3>
<p>Application in The Optimizely Connect Platform acts as an integration layer between commerce and content systems. It:</p>
<ul>
<li>
<p>Listens to webhooks from the commerce layer (e.g., product updates)</p>
</li>
<li>
<p>Synchronizes product and content data into Optimizely Graph</p>
</li>
<li>
<p>Updates the content stored in Optimizely SaaS CMS</p>
</li>
</ul>
<p>This makes it easy to keep the product catalog and content in sync without manual intervention.</p>
<h3><strong>🔵 Optimizely Graph</strong></h3>
<p>Serves as the central source of truth for the frontend, containing:</p>
<ul>
<li>
<p>Product data</p>
</li>
<li>
<p>CMS content</p>
</li>
<li>
<p>Searchable indexes</p>
</li>
</ul>
<p>The headless frontend communicates with this API to render all pages dynamically and efficiently.</p>
<h3><strong>🟢 Optimizely SaaS CMS</strong></h3>
<p>Allows content authors to create and manage content using the Visual Builder. Published content is automatically indexed in Optimizely Graph, making it available to the frontend without delay.</p>
<h3><strong>⚫ Headless Application (Frontend)</strong></h3>
<p>The frontend is fully headless and consumes all data via APIs. It:</p>
<ul>
<li>
<p>Takes product information from only one place - Optimizely Graph</p>
</li>
<li>
<p>Fetches CMS, product, and category pages from Optimizely Graph</p>
</li>
<li>
<p>Handles cart, checkout, and order history by communicating with the commerce layer</p>
</li>
<li>
<p>Uses identifiers like productId, variantId, and SKU to render product data</p>
</li>
</ul>
<h3><strong>Data Flow Summary</strong></h3>
<ul>
<li>
<p><strong>PIM → Commerce</strong>: Product data and metafields are synced</p>
</li>
<li>
<p><strong>Commerce → Connect:</strong> Webhooks notify changes</p>
</li>
<li>
<p><strong>Connect → Graph & CMS:</strong> Data is synced into Optimizely</p>
</li>
<li>
<p><strong>CMS → Graph:</strong> Content is indexed</p>
</li>
<li>
<p><strong>Frontend → Graph:</strong> Frontend fetches all content and product data via GraphQL</p>
</li>
<li>
<p><strong>Frontend ↔ Commerce:</strong> Handles user interactions like checkout, login and cart</p>
</li>
</ul>
<p><strong> </strong></p>
<h2><strong>Comparison: With OCP vs. Without OCP</strong></h2>
<div align="left">
<table style="border-collapse: collapse; border: 2px solid rgb(0, 0, 0); background-color: rgb(255, 255, 255); width: 71.307%; height: 447.938px;">
<tbody>
<tr style="height: 47.5938px;">
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 15.435%; height: 47.5938px;">
<p>Feature</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 46.1964%; height: 47.5938px;">
<p>Without OCP</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 38.3702%; height: 47.5938px;">
<p>With OCP</p>
</td>
</tr>
<tr style="height: 47.5938px;">
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 15.435%; height: 47.5938px;">
<p>Data Ownership</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 46.1964%; height: 47.5938px;">
<p>Split: PIM, Commerce, CMS all manage data</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 38.3702%; height: 47.5938px;">
<p>Centralized: Optimizely Graph owns all product data</p>
</td>
</tr>
<tr style="height: 67.1875px;">
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 15.435%; height: 67.1875px;">
<p>Commerce Data Flow</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 46.1964%; height: 67.1875px;">
<p>PIM → Commerce → Headless App</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 38.3702%; height: 67.1875px;">
<p>PIM → Commerce → OCP → Graph → Headless App</p>
</td>
</tr>
<tr style="height: 47.5938px;">
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 15.435%; height: 47.5938px;">
<p>Revalidation Speed</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 46.1964%; height: 47.5938px;">
<p>Fast (direct read from Commerce & Graph)</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 38.3702%; height: 47.5938px;">
<p>Slower (delayed by syncs from PIM via OCP)</p>
</td>
</tr>
<tr style="height: 47.5938px;">
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 15.435%; height: 47.5938px;">
<p>Cache Invalidation</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 46.1964%; height: 47.5938px;">
<p>Manual or real-time via CMS/Commerce hooks</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 38.3702%; height: 47.5938px;">
<p>Delayed due to webhook-based multi-step sync</p>
</td>
</tr>
<tr style="height: 47.5938px;">
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 15.435%; height: 47.5938px;">
<p>Dev Complexity</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 46.1964%; height: 47.5938px;">
<p>High – headless app merges two APIs</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 38.3702%; height: 47.5938px;">
<p>Low – one API (Graph) handles CMS/product info</p>
</td>
</tr>
<tr style="height: 47.5938px;">
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 15.435%; height: 47.5938px;">
<p>Sync Complexity</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 46.1964%; height: 47.5938px;">
<p>High – headless app needs to listen to changes from two sources</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 38.3702%; height: 47.5938px;">
<p>Low – one API (Graph)</p>
</td>
</tr>
<tr style="height: 47.5938px;">
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 15.435%; height: 47.5938px;">
<p>Real-time Accuracy</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 46.1964%; height: 47.5938px;">
<p>High – data is fetched live</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 38.3702%; height: 47.5938px;">
<p>Lower – sync delays might cause stale content</p>
</td>
</tr>
<tr style="height: 47.5938px;">
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 15.435%; height: 47.5938px;">
<p>Scalability</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 46.1964%; height: 47.5938px;">
<p>Moderate – more API calls from frontend</p>
</td>
<td style="border-color: rgb(0, 0, 0); border-width: 2px; width: 38.3702%; height: 47.5938px;">
<p>High – Graph acts as single fast CDN source</p>
</td>
</tr>
</tbody>
</table>
</div>
<p><strong> </strong></p>
<h3><strong>Pros of the Hub-based Architecture:</strong></h3>
<ul>
<li>
<p><strong>Central source of truth</strong> – all data is stored in the Optimizely Graph</p>
</li>
<li>
<p><strong>Simplified frontend</strong> – all product and CMS data comes from Optimizely Graph</p>
</li>
<li>
<p><strong>Better control</strong> over content and data ownership across teams</p>
</li>
<li>
<p><strong>More scalable</strong> due to optimized data serving from Graph/CDN</p>
</li>
<li>
<p><strong>Easier to manage</strong> localization and content enrichment</p>
</li>
</ul>
<h3><strong>Cons of the Hub-based Architecture:</strong></h3>
<ul>
<li>
<p><strong>Slower cache revalidation</strong> – changes need to pass through multiple systems before appearing in the frontend</p>
</li>
<li>
<p><strong>Data freshness challenges</strong> – frontend content may be affected by delays in webhook chains</p>
</li>
</ul>
<p><strong> </strong></p>
<h2><strong>Transactional Commerce Services</strong></h2>
<p>Both architectures support a wide range of modern SaaS commerce platforms, such as:</p>
<ul>
<li>
<p>Shopify</p>
</li>
<li>
<p>BigCommerce</p>
</li>
<li>
<p>commercetools</p>
</li>
<li>
<p>Commerce Layer</p>
</li>
<li>
<p>Salesforce Commerce Cloud</p>
</li>
<li>
<p>And many others</p>
</li>
</ul>
<p>While the core functionality of these platforms is similar, there are subtle differences in data models and APIs. For example:</p>
<ul>
<li>
<p><strong>Shopify </strong>does not expose a product SKU directly. Instead, SKUs exist only at the variant level.</p>
</li>
<li>
<p><strong>BigCommerce</strong>, on the other hand, supports both product-level SKUs and variant SKUs.</p>
</li>
</ul>
<p>Different commerce platforms may have varying data models, but the <strong>overall architecture remains consistent</strong> regardless of the specific platform chosen.</p>
<h2>Real-World Example: Custom Composable Commerce Architecture</h2>
<p>Let me share a more complex real-world implementation that we at <a title="Hatimeria " href="https://www.hatimeria.com/">Hatimeria</a> developed for a client. This architecture demonstrates how composable commerce can be customized to meet specific business needs:</p>
<p> </p>
<p><strong> <img src="/link/848cfd62dd354003b76da793d76b4df8.aspx?1747646375099" width="1200" height="490" /></strong></p>
<p>The following example illustrates:</p>
<ul>
<li class="">
<p class=""><strong>PIM (Pimcore)</strong>: Stores enriched product data in BigCommerce metafields - availability, variants, pricing per user group, inventory, status, subscription flag, loyalty points, alternatives, etc.</p>
</li>
<li class="">
<p class=""><strong>SaaS CMS</strong>: Single source of truth for product content (title, images, description), CMS pages, blocks, and transactional content. Product content linked via SKU.</p>
</li>
<li class="">
<p class=""><strong>BigCommerce</strong>: Core commerce engine - customer data, cart logic, checkout setup, payment, and reporting. Stores product base info and PIM metafields.</p>
</li>
<li class="">
<p class=""><strong>Checkout (BigCommerce SDK + Azure Functions)</strong>: Custom checkout UI. Promo codes and final calculations are processed via Azure Functions, not native BigCommerce.</p>
</li>
<li class="">
<p class=""><strong>Promotions (.NET Engine)</strong>: Custom UI for managing promotions - define conditions (customer, product, time-based), rewards (discounts, gifts, points). Stored in a database.</p>
</li>
<li class="">
<p class=""><strong>Azure Functions</strong>: Handle advanced cart logic - fetch data from BigCommerce, CMS, and customer service, validate products, apply promotions, and update cart metafields.</p>
</li>
<li class="">
<p class=""><strong>Algolia</strong>: Fast search and category results. Index updated hourly and via real-time webhooks from CMS and BigCommerce.</p>
</li>
<li class="">
<p class=""><strong>Headless App (Next.js)</strong>: Orchestrates frontend - content from CMS, products merged via SKU from BigCommerce + CMS, search from Algolia, cart/promo logic via Azure. Checkout handled on separate domain via BigCommerce SDK.</p>
</li>
</ul>
<p class=""><strong>Data Flow Highlights</strong>:</p>
<ul>
<li class="">
<p class=""><strong>PIM ➜ BigCommerce </strong>(metafields)</p>
</li>
<li class="">
<p class=""><strong>CMS ➜ Headless App</strong> (content, product info)</p>
</li>
<li class="">
<p class=""><strong>BigCommerce ➜ Headless App</strong> (products, cart)</p>
</li>
<li class="">
<p class=""><strong>Headless App ➜ Azure Functions</strong> (cart calculation & validation)</p>
</li>
<li class="">
<p class=""><strong>Azure Functions ➜ BigCommerce</strong> (cart metafield updates)</p>
</li>
<li class="">
<p class=""><strong>Webhooks (BigCommerce/CMS) ➜ Headless App ➜ Algolia</strong> (real-time reindex)</p>
</li>
</ul>
<p>This modular setup ensures agility, enables deep customization at every stage of the customer journey, and supports a real-time, high-performance commerce experience.<br />Implementing such an architecture wasn’t easy - it required significant effort and deep technical alignment across services. But to stay ahead of the competition and meet ambitious business requirements, such as fully custom promotion logic that no out-of-the-box platform could support, this level of complexity was essential. <strong>After all, this shouldn’t be simple — this is business critic</strong></p>
<h2>Key Takeaways</h2>
<ul>
<li>
<p><strong>Without Optimizely Connect Platform:</strong> Offers greater flexibility and real-time access to data but can be more complex and harder to manage, especially when dealing with multiple APIs.</p>
</li>
</ul>
<ul>
<li>
<p><strong>With Optimizely Connect Platform:</strong> Simplifies integration, centralizes data management, and enhances scalability, though there may be some delay in data synchronization.</p>
</li>
</ul>
<p>Both approaches are powerful, and the choice depends on the specific needs of your business and the complexity of the system you’re building.</p>
<h2>Final Thoughts</h2>
<p>The architectures discussed demonstrate the power and flexibility of building composable commerce solutions with Optimizely. By separating concerns between Product Information Management, Transactional Commerce Services, Optimizely Graph, and a Headless Application, we can create highly scalable, customizable, and performant ecosystems tailored exactly to business needs.</p>
<p>While the diagrams presented here are conceptual and simplified for clarity, in real-world scenarios many more factors must be considered, including authentication, caching, synchronization challenges, failover strategies, and others. However, the core beauty of composable architecture remains clear: it allows us to easily integrate new services, extend features from different providers, and orchestrate everything within a single, unified headless application.</p>
<p>The<strong> Optimizely Connect Platform</strong> can be an <strong>incredibly powerful tool </strong>in this landscape, offering a modern way to stitch together content, commerce, and search across distributed systems with great performance and flexibility.</p>
<p>Combining multiple systems is never trivial - it requires deep technical expertise, a strong architectural vision, and the ability to navigate integration challenges. But when executed properly, it unlocks tremendous value and creates best-in-class digital experiences.</p>
<h2>Explore More</h2>
<p>If you'd like to see composable commerce with Optimizely in action, check out these resources:</p>
<ul>
<li>
<p><a href="https://opti-sass.vercel.app/">Composable Commerce with Feature Experimentation</a> - See how feature flags can help you test different commerce services (Shopify vs BigCommerce)</p>
</li>
<li>
<p><a href="https://optimizely-one-nu.vercel.app/">Optimizely SaaS CMS with Shopify</a> - A working example of the first architecture</p>
</li>
<li>
<p><a href="https://opti-masterclass.vercel.app/">Headless using Optimizely SaaS CMS course</a> - Learn how to get started</p>
</li>
<li>
<p><a href="https://optimizely-masterclass.vercel.app/">Content-rich website using Optimizely SaaS CMS</a> - See a simple implementation</p>
</li>
</ul>2025-04-30T13:01:23.0000000ZBlog postA Free Course for Building Headless Applications with Next.js and Optimizely SaaS CMS<p>I am excited to announce the transformation of Optimizely Headless CMS webinar into a comprehensive, <strong>completely free</strong> self-paced course that's available to everyone - <strong>no registration required</strong>.</p>
<p><strong><a title="Visit the Optimizely Masterclass website now " href="https://opti-masterclass.vercel.app">Visit the Course website now</a></strong></p>
<p> </p>
<p><img src="/link/86c3bc71343442938c2ec7405bfb5d3a.aspx" /></p>
<h2>From Time-Limited Webinar to Always-Available Learning Resource</h2>
<p>What started as a one-time webinar has evolved into something much more valuable: a permanent, accessible learning resource for developers of all skill levels. I've reimagined the content to create a step-by-step guide that allows you to learn at your own pace, whenever it fits your schedule.</p>
<p>The best part? <strong>No registration forms, no email collection, no barriers to entry</strong>. Simply visit the site and start learning immediately.</p>
<h2>Learn to Build Scalable Headless Applications with Next.js and Optimizely SaaS CMS</h2>
<p>The course guides you through building a modern, high-performance website using Next.js and Optimizely's SaaS CMS. Whether you're new to headless architecture or looking to refine your skills, this course provides clear, practical instruction for developers at every level.</p>
<p>Here's what you'll learn:</p>
<ul>
<li>Setting up a Next.js project with Optimizely SaaS CMS</li>
<li>Creating a flexible block factory pattern for content components</li>
<li>Implementing efficient image loading and optimization</li>
<li>Building dynamic routes with Next.js App Router</li>
<li>Designing responsive layouts with v0</li>
<li>Modeling content effectively in Optimizely CMS</li>
<li>Writing optimized GraphQL queries for content delivery</li>
<li>Implementing multi-language support and localization</li>
<li>Handling preview mode</li>
<li>Implementing Visual Builder support</li>
<li>Mastering cache revalidation</li>
</ul>
<p>Each concept is explained with practical code examples that you can immediately apply to your own projects.</p>
<h2>Follow Along with GitHub: Start from Any Point in the Journey</h2>
<p>One of the most powerful features of this course is its companion GitHub repository, where each step is meticulously documented on a separate branch. This innovative approach allows you to:</p>
<ul>
<li>Jump in at any point in the learning process</li>
<li>Compare your code with working examples</li>
<li>See exactly how the application evolves from start to finish</li>
<li>Experiment with different approaches without breaking your progress</li>
</ul>
<p><br />If you get stuck or want to skip ahead, simply check out the corresponding branch and continue your learning journey without missing a beat.</p>
<p><img src="/link/7e944ad51a894274813f02bfd1949cf4.aspx" /></p>
<h2>Designed for Real-World Application</h2>
<p>This isn't just a theoretical exercise - you'll build a complete, production-ready website that showcases the power of headless architecture. The course emphasizes best practices for performance, scalability, and maintainability, ensuring that what you learn can be directly applied to your professional projects.</p>
<p>By the end of the course, you'll have:</p>
<ul>
<li>A fully functional Next.js website powered by Optimizely SaaS CMS</li>
<li>A deep understanding of headless architecture principles</li>
<li>Practical experience with modern development workflows</li>
<li>Code patterns you can reuse in future projects</li>
</ul>
<h2>Start Learning Today - No Strings Attached</h2>
<p>I believe in removing barriers to education, which is why this course is completely free and requires no registration. You won't need to create an account, provide your email, or jump through any hoops to access the full content.</p>
<p><strong><a title="Visit the Optimizely Masterclass website now " href="https://opti-masterclass.vercel.app">Visit the Course website now</a></strong></p>2025-03-24T19:00:05.0000000ZBlog postOptimizely Graph and Next.js: Building Scalable Headless Solutions<div>Optimizely Graph harnesses the capabilities of GraphQL, an intuitive and efficient query language to, transform content within an Optimizely CMS into a structured, interconnected graph. Complementing this, Next.js, a React-based frontend framework, empowers developers to build performant and SEO-friendly web applications, enabling static and dynamic rendering and many more amazing features that can enhance your headless solution.</div>
<div> </div>
<div> </div>
<div>In this article we delve into the symbiotic relationship between Optimizely Graph and Next.js, exploring how this pairing facilitates the crafting of dynamic headless experiences, from enabling draft modes and On-Page Editing to harnessing static site generation. We'll also investigate the utilization of webhooks for efficient page revalidation, enabling seamless updates across web applications.</div>
<h2>What is Optimizely Graph used for?</h2>
<div>Using Optimizely Graph we are able to separate our admin panel from our application, the so called headless, since we have two separate applications that are independent of each other. Headless in Optimizely has long been possible by using the Content Delivery API, but Graph simplifies a lot of things.</div>
<div> </div>
<div><img src="https://hatimeriacom-strapi.s3.eu-central-1.amazonaws.com/What_is_the_Optimizely_Graph_used_for_8ca91c5920.png" width="600" alt="What is the Optimizely Graph used for?" height="307" style="display: block; margin-left: auto; margin-right: auto;" /></div>
<h2></h2>
<h2>How does Optimizely Graph work?</h2>
<div>Optimizely Graph is a separate service that is hosted on a CDN, made fast by implementing the latest, most modern technologies using global serverless Edge computing, auto scaling microservices and the latest search engine.</div>
<div> </div>
<div>There are two ways to deliver content to the Graph service:</div>
<div> </div>
<ol>
<li>Scheduled job </li>
<li>Event Triggering, for example publishing a page.</li>
</ol>
<div>The Content Delivery API is used under the hood, delivering content to Graph. When you want to introduce something custom, such as adding business logic to a block, you can do so using an override of the serialization used in the Content Delivery API.</div>
<div> </div>
<div>In the image below we can see how the Optimizely Graph works. It all starts in the admin panel, in the picture labeled with the Optimizely logo. From there, using the Content Delivery API, the content goes to the GraphQl Server. GraphQl Server is hosted on Azure and is embedded on a CDN. The GraphQl Server combines the admin panel and frontend application used by users. The frontend application communicates directly with GraphQl Server, receiving all the necessary data.</div>
<div> </div>
<div><img src="https://hatimeriacom-strapi.s3.eu-central-1.amazonaws.com/How_does_Optimizely_Graph_work_a603841a7d.png" width="600" alt="How does Optimizely Graph work?" height="433" style="display: block; margin-left: auto; margin-right: auto;" /></div>
<div>Source: <a href="/link/386fb3fd598c4978aaf6906a1bbc1505.aspx">world.optimizely.com</a></div>
<h2>Support for Commerce</h2>
<div>As of early December, Optimizely Graph has been officially released and is production ready. The released version supports CMS only and allows read-only options. At a recent webinar held by Optimizely, the company said that they are getting a lot of requests for Commerce support and it is in the approval stage by Project Management. Keeping in mind that commerce is much more complicated than CMS, it may take longer to work on this. In summary, currently no work is being done to implement support for commerce, and once this plan is approved, we will have to wait a while for it to be ready for use in production. However, using other Optimizely products using Content Delivery API, we are able to implement Headless Commerce. There is also an option to use Graph for CMS-related stuff, and Content Delivery API for commerce-related stuff.</div>
<h2>Personalization</h2>
<div>Personalization as we know it so far, i.e. creating visitor groups and adding personalization in Content Area and XHTML strings, **will not work**.</div>
<div>Here's where other products can help, like Optimizely Web Experimentation, where you can create personalized campaigns and immediately measure which variance converts better. However, this is an additional product charged separately.</div>
<div> </div>
<div>There is another option that is being worked on: the integration of Optimizely Graph with Optimizely Data Platform RLS (Real Time Segment), which is the next generation of “Visitor Groups”. ODP is also an additional product that is charged separately.</div>
<h2>Content Recommendations</h2>
<div>Content Recommendation works by scraping the page source of the site. if it is valid HTML, there should be no problem with it. If we use Server Side Rendering, there is pure HTML code in the page source, so with SSR, Content Recommendations works. The problem with Content Recs is that if you choose client-side rendering, it means that non-native HTML elements such as <teaser-block/> are included in HTML, so the scraper is not able to collect the correct data.</div>
<h2>Hosting on DXP</h2>
<div>It is possible to continue to have the frontend application hosted on DXP, then the client app (Node.js) and the backend (.net) are served on the same address by proxying requests from .net to the Node.js process. An example of such a solution can be found <a href="https://github.com/episerver/Foundation-spa-react">here</a></div>
<div> </div>
<div><img src="https://hatimeriacom-strapi.s3.eu-central-1.amazonaws.com/Hosting_on_DXP_440821d35c.png" width="600" alt="Hosting on DXP" height="241" style="display: block; margin-left: auto; margin-right: auto;" /></div>
<div>Source: <a href="https://github.com/episerver/content-delivery-js-sdk/tree/master/samples/music-festival-vue-coupled#backend">Github</a></div>
<div> </div>
<div>Vercel is the recommended hosting platform for Next.js to fully leverage its capabilities, such as <a href="https://vercel.com/docs/incremental-static-regeneration">Incremental Static Regeneration (ISR)</a> <a href="https://vercel.com/templates/next.js/on-demand-incremental-static-regeneration">(example of code)</a>, image and font optimization. By hosting Next.js on Vercel, you can achieve better performance due to its seamless integration with Next.js and support for these advanced features.</div>
<div> </div>
<div>Vercel's administration panel provides a user-friendly interface for managing deployments, making it accessible even to non-technical users. This allows for easy deployment to production after reviewing changes on staging. While there are inherent risks in allowing non-technical users to deploy changes, for small changes like increasing font size, the risks are minimal. The clear and intuitive interface of Vercel's administration panel makes it convenient for non-technical users to manage deployments with confidence.</div>
<div> </div>
<div>An example of a starter for Optimizely Feature Flags with Next.js is available for preview and use here.</div>
<h2>Understanding Next.js Rendering Strategies</h2>
<div>Next.js employs three main server rendering strategies:</div>
<div> </div>
<div>1. <strong>Static Rendering (Default)</strong>: Routes are pre-rendered at build time or after data revalidation. The rendered result is cached and can be distributed via Content Delivery Networks (CDN). This strategy is suitable for static content like blog posts or product pages.</div>
<div>2. <strong>Dynamic Rendering</strong>: Routes are rendered for each user at request time. This method is ideal for personalized data or information specific to each user, such as cookies or search parameters.</div>
<div>3. <strong>Dynamic Routes with Cached Data</strong>: Next.js allows for routes with a mix of cached and uncached data. This flexibility means you can have personalized, dynamic content while benefiting from caching. For instance, an e-commerce page might use cached product data along with uncached, personalized customer information.</div>
<div> </div>
<div>These server rendering strategies offer benefits like enhanced performance, improved security and better initial page load times. Leveraging Next.js's capabilities, developers can efficiently manage and render content, allowing for highly personalized and dynamic web experiences in your headless solution.</div>
<h3>Fetching data from Optimizely Graph</h3>
<div>A very useful thing when working with Optimizely Graph is codegen for GraphQL Schema - `@graphql-codegen/cli`. With this tool, all we need to do is create the appropriate snippets or queries for our Optimizely Graph, and the CLI will generate a fully-typed SDK for us.</div>
<div> </div>
<div>Let’s configure our codegen. First, install following dependencies:</div>
<div>
<pre class="language-javascript"><code>npm i -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-generic-sdk @graphql-codegen/typescript-operations</code></pre>
</div>
<div> </div>
<div> </div>
<div>Now, we need to create a config file where we define plugins, schema source, destination file etc.</div>
<div> </div>
<div>
<pre class="language-javascript"><code>// codegen.yaml
schema: ${OPTIMIZELY_API_URL}?auth=${OPTIMIZELY_SINGLE_KEY}
documents: './src/graphql/**/*.graphql'
generates:
'./src/types/generated.ts':
plugins:
- 'typescript'
- 'typescript-operations'
- 'typescript-generic-sdk'
config:
rawRequest: true
avoidOptionals: true</code></pre>
</div>
<div> </div>
<div>This configuration will make sure that our SDK and types will be generated in the <strong>./src/types/generated.ts</strong> based on the Optimizely Graph schema and fragments and queries defined in the <strong>./src/graphql/*</strong>.</div>
<div>Now, let’s create our custom fetcher that we will use to query data from the Optimizely Graph.</div>
<div> </div>
<div>
<pre class="language-javascript"><code>interface OptimizelyFetchOptions {
headers?: Record<string, string>
cache?: RequestCache
preview?: boolean
}
interface OptimizelyFetch<Variables> extends OptimizelyFetchOptions {
query: string
variables?: Variables
}
export const optimizelyFetch = async <Response, Variables = {}>({
query,
variables,
headers,
cache = 'force-cache',
preview,
}: OptimizelyFetch<Variables>): Promise<GraphqlResponse<Response> & { headers: Headers }> => {
const configHeaders = headers ?? {}
if (preview) {
configHeaders.Authorization = `Basic ${process.env.OPTIMIZELY_PREVIEW_SECRET}`
}
try {
const endpoint = `${process.env.OPTIMIZELY_API_URL}?auth=${process.env.OPTIMIZELY_SINGLE_KEY}`
const response = await fetch(endpoint, {
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
...configHeaders,
},
body: JSON.stringify({
...(query && { query }),
...(variables && { variables }),
}),
cache,
})
const result = await response.json()
return {
...result,
headers: response.headers,
}
} catch (e) {
if (isVercelCommerceError(e)) {
throw {
status: e.status || 500,
message: e.message,
query,
}
}
throw {
error: e,
query,
}
}
}</code></pre>
</div>
<div> </div>
<div>The <strong>`process.env.OPTIMIZELY_PREVIEW_SECRET`</strong> variable is a generated base64 string based on your AppKey and AppSecret credentials. For more details I recommend you to take a look at <a href="https://kunalshetye.com/posts/optimizely-graph-using-appkey-appsecret/">Kunal’s article</a></div>
<div> </div>
<div>Let’s create a wrapper function around our <strong>`optimizelyFetch`</strong> that maps the values properly to the <strong>`getSdk`</strong> function which is an auto-generated SDK.</div>
<div> </div>
<div>
<pre class="language-javascript"><code>async function requester<R, V>(doc: DocumentNode, vars?: V, options?: OptimizelyFetchOptions) {
const request = await optimizelyFetch<R>({
query: print(doc),
variables: vars ?? {},
...options,
})
return {
data: request.data,
_headers: request.headers,
}
}
export const optimizely = getSdk(requester)</code></pre>
</div>
<div> </div>
<div>In the <strong>`./src/graphql`</strong> (path defined in the `<strong>documents</strong>` field in the codegen configuration file) create your first query:</div>
<div> </div>
<div>
<pre class="language-javascript"><code>// GetContentById.graphql
query GetContentById($id: Int, $workId: Int) {
Content(where: { ContentLink: { Id: { eq: $id }, WorkId: { eq: $workId } } }) {
items {
Name
RelativePath
ContentLink {
Id
}
}
}
}</code></pre>
</div>
<div> </div>
<div>After properly configuring codegen and firing the command that generates the SDK, we get a fully-typed client.</div>
<div> </div>
<div><img src="https://hatimeriacom-strapi.s3.eu-central-1.amazonaws.com/typed_client_89b42f0bf5.png" width="490" alt="fully typed client" height="209" style="display: block; margin-left: auto; margin-right: auto;" /></div>
<div> </div>
<h3>Draft Mode with Optimizely Graph and Next.js</h3>
<div>With Optimzely and Next.js we can easily configure previews, drafts and on-page editing to fully take advantage of the headless architecture. In order to let Optimizely know what is the URL to our Frontend, we need to follow a few simple steps.</div>
<div> </div>
<div>Firstly, go to the <strong>`Manage Websites`</strong> section in the CMS settings. Go ahead and create a website. The important thing at this point will be to set the appropriate host names. You need to add one line for the backend application and one for the frontend application, remembering to set the Primary type for the frontend application:</div>
<div> </div>
<div><img src="https://hatimeriacom-strapi.s3.eu-central-1.amazonaws.com/manage_websites_cms_settings_532e7bb0ed.png" width="600" alt="Manage websites cms settings" height="512" style="display: block; margin-left: auto; margin-right: auto;" /></div>
<div> </div>
<div>At this point, Optimizely will know what URL to use for Preview Mode iframe and for the <strong>`View on website`</strong> button.</div>
<div> </div>
<div>Now, let’s handle displaying correct route in the Preview Mode. By default, the generated URL adds <strong>`/episerver/cms/content/**/*`</strong> pathname to the configured host and passes it to the iframe. We can redirect all requests from that URL to our custom API handler that will turn on the <a href="https://nextjs.org/docs/app/building-your-application/configuring/draft-mode">draft mode</a> for the corresponding page.</div>
<div> </div>
<div>
<pre class="language-javascript"><code>// next.config.js
async redirects() {
return [
{
source: '/episerver/cms/content/:path*',
destination: '/api/draft/:path*',
permanent: false,
},
]
},</code></pre>
</div>
<div> </div>
<div>Example: <strong>`EPiServer/CMS/Content/en/artists/almost-up-today,,35/`</strong> is redirected to <strong>`api/draft/en/artists/almost-up-today,,35/`</strong></div>
<div><strong> </strong></div>
<div>Create an <a href="https://nextjs.org/docs/app/building-your-application/routing/route-handlers">API route</a> that will handle the draft mode:</div>
<div> </div>
<div>
<pre class="language-javascript"><code>// api/draft/[[...content]]/route.ts
export async function GET(request: NextRequest, { params }: { params: { content: string[] } }) {
const { searchParams } = new URL(request.url)
const token = searchParams.get('preview_token')
const payload = decodeToken(token)
const contentId = payload?.contentId
const contentWorkId = payload?.contentWorkId
const { slugs } = getSlugs(params.content)
if (!slugs || !contentId || !token) {
return notFound()
}
const newPathname = slugs.join('/')
const { data, errors } = await optimizely.GetContentById(
{ id: contentId, workId: contentWorkId ?? null },
{ preview: true }
)
if (errors) {
const errorsMessage = errors.map((error) => error.message).join(', ')
return new Response(errorsMessage, { status: 401 })
}
draftMode().enable()
cookies().set(PREVIEW_TOKEN_COOKIE_NAME, token)
redirect(`/${newPathname}`)
}</code></pre>
</div>
<div> </div>
<div>The <strong>`[[…content]]`</strong> segment is a <a href="https://nextjs.org/docs/app/building-your-application/routing#file-conventions">naming convention</a> that let’s you catch all route segments, which will be available in the params object argument.</div>
<div>Let’s handle the draft mode in the Page component:</div>
<div> </div>
<div>
<pre class="language-javascript"><code>export default async function HomePage() {
const { isEnabled: isDraftModeEnabled } = draftMode()
let pageResponse
if (isDraftModeEnabled) {
const preview_token = cookies().get(PREVIEW_TOKEN_COOKIE_NAME)
if (!preview_token) {
return notFound()
}
const payload = decodeToken(preview_token.value)
const contentId = payload?.contentId ?? null
const workId = payload?.contentWorkId ?? null
pageResponse = await optimizely.StartPageQuery(
{ contentId, workId },
{ preview: true, cache: 'no-store' }
)
} else {
pageResponse = await optimizely.StartPageQuery()
}
const startPage = pageResponse.data?.StartPage?.items?.[0]
if (!startPage) {
return notFound()
}
return (
<div className="container mx-auto py-10">
<div className="w-full px-4">
<h1 className="text-3xl font-bold mb-10 max-w-prose" data-epi-edit="TeaserText">
{startPage.TeaserText}
</h1>
</div>
<ContentAreaMapper blocks={startPage.MainContentArea} />
</div>
)
}</code></pre>
</div>
<div> </div>
<div>Be careful here though - using cookies in a page component turns it to be dynamically rendered - unless it’s used in <strong>`if`</strong> block that checks for the draft mode.</div>
<div> </div>
<div>The optimizely script to utilize On-Page Editing feature:</div>
<div> </div>
<div>
<pre class="language-javascript"><code>import Script from 'next/script'
import { draftMode } from 'next/headers'
export default function RootLayout({ children }: { children: React.ReactNode }) {
const { isEnabled: isDraftModeEnabled } = draftMode()
return (
<>
{isDraftModeEnabled && <Script src={`${process.env.OPTIMIZELY_BACKEND_URL}/episerver/cms/latest/clientresources/communicationinjector.js`} />}
<html lang="en">
<body className={inter.className}>
<MainLayout>{children}</MainLayout>
</body>
</html>
</>
)
}</code></pre>
</div>
<div> </div>
<div><img src="https://hatimeriacom-strapi.s3.eu-central-1.amazonaws.com/draft_mode_60b2777b4c.gif" width="600" alt="Draft Mode" height="314" style="display: block; margin-left: auto; margin-right: auto;" /></div>
<div> </div>
<h4>data-epi-edit</h4>
<div>To enable on page editing (OPE) we need to add an attribute to the html that will enable this, you can read more about it in the <a href="https://docs.developers.optimizely.com/platform-optimizely/v1.4.0-optimizely-graph/docs/on-page-editing-using-content-graph#make-a-property-editable">documentation</a></div>
<div> </div>
<div>
<pre class="language-javascript"><code><div className="container mx-auto py-10">
<div className="w-full px-4">
<h1 data-epi-edit="TeaserText" className="text-3xl font-bold mb-10 max-w-prose">
{startPage?.TeaserText}
</h1>
</div>
<ContentAreaMapper blocks={startPage?.MainContentArea} />
</div></code></pre>
</div>
<div> <img src="https://hatimeriacom-strapi.s3.eu-central-1.amazonaws.com/ope_8c403ea48a.png" width="600" alt="ope" height="270" style="display: block; margin-left: auto; margin-right: auto;" /></div>
<h2>Static Site Generation</h2>
<div>Static Site Generation (SSG) is a powerful feature in Next.js that enables the pre-rendering of pages at build time. During the build process, Next.js generates HTML files for each page in your application. These HTML files are static, meaning they represent the state of the page at the time of the build. The pre-rendered HTML files can be served to users without requiring server-side rendering for every request.</div>
<div> </div>
<div><span style="font-size: 14pt;"><strong>Benefits of Static Site Generation in Next.js:</strong></span></div>
<div><span style="font-size: 14pt;"><strong></strong></span></div>
<div>1. <strong>Improved Performance:</strong> Since the pages are pre-rendered at build time, users receive static HTML files, reducing the need for server-side processing during runtime. This leads to faster page loads and improved overall performance.</div>
<div>3. <strong>SEO Optimization</strong>: Search engines favor static HTML content. SSG helps improve search engine optimization (SEO) by providing crawlers with easily indexable and readable content. This can positively impact a website's search engine ranking.</div>
<div>4. <strong>Lower Server Load</strong>: Static pages can be served directly from a content delivery network (CDN) without the need for server-side processing. This reduces the load on the server, allowing it to handle more concurrent users efficiently.</div>
<div>5. <strong>Cost Efficiency:</strong> Serving static content is typically more cost-effective than dynamically generating content for each user request. With SSG, you can generate pages during the build process, reducing the need for server resources during runtime.</div>
<div>6. <strong>Better User Experience:</strong> Static pages load quickly, providing a smoother and more responsive user experience. Users see the content faster, leading to higher user satisfaction and engagement.</div>
<div>7. <strong>CDN Compatibility:</strong> Static files can be easily distributed across a content delivery network, ensuring that the content is delivered from servers geographically closer to the user. This minimizes latency and further enhances page load times.</div>
<div>8. <strong>Offline Support:</strong> Static pages can be easily cached, enabling offline access for users. Once the pages are loaded, they can be stored in the browser cache, allowing users to access the content even without an internet connection.</div>
<div> </div>
<div> </div>
<div><strong>How to Achieve This with Optimizely Graph:</strong></div>
<div><strong> </strong></div>
<div>In Next.js, there is a method called <strong><a href="https://nextjs.org/docs/app/api-reference/functions/generate-static-params">generateStaticParams</a> </strong>that must return all static routes. To obtain this information, we need to query Optimizely Graph for all routes:</div>
<div> </div>
<div>The GraphQL query to the Content Graph:</div>
<div>
<pre class="language-javascript"><code>query AllPages($pageType: [String]) {
Content(locale: en, where: { ContentType: { in: $pageType } }) {
items {
Name
RelativePath
RouteSegment
ContentType
}
}
}</code></pre>
</div>
<div> </div>
<div>Implementation in TypeScript:</div>
<div> </div>
<div>
<pre class="language-javascript"><code>import { optimizely } from '@/api/optimizely'
export const getStandardPagesUrls = async () => {
const pages = await optimizely.AllPages({ pageType: 'StandardPage' })
const pagesWithUrls = pages?.data?.Content?.items?.filter((page) => !!page?.RelativePath)
const paths = pagesWithUrls?.map((page) => {
const segments = page?.RelativePath?.split('/').filter(String)
return {
name: page?.Name,
segments: segments,
path: page?.RelativePath,
}
})
return paths
}</code></pre>
</div>
<div> </div>
<div>Considering that our project uses <strong>`[[…page]]`</strong> (check <a href="https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments">Next.js Dynamic Routes)</a>, we need to split the path into a string array, such as /en/alloy-meet ⇒ [’en’, ‘alloy-meet’]. Therefore, we perform a split operation</div>
<div> </div>
<div>
<pre class="language-javascript"><code>export async function generateStaticParams() {
try {
const paths = await getStandardPagesUrls()
return paths?.map((path) => path.segments) ?? []
} catch (e) {
console.error(`Failed to retrieve static pages: ${e}`)
return []
}
}</code></pre>
</div>
<div> </div>
<div>In summary, Static Site Generation in Next.js offers a way to generate performant, SEO-friendly, and cost-effective websites by pre-rendering pages at build time. It leverages the benefits of static content while providing the flexibility and convenience of a dynamic web framework.</div>
<div> </div>
<h3>Using Webhooks for Page Revalidation (ISR)</h3>
<div>Let's start by understanding what ISR (Incremental Static Regeneration) is.</div>
<div> </div>
<div>Next.js empowers you to create or update static pages *after* building your site. Incremental Static Regeneration (ISR) allows you to utilize static generation on a per-page basis, <strong>eliminating the need to rebuild the entire site</strong>. With ISR, you can maintain the advantages of static pages while effortlessly scaling to millions.</div>
<div> </div>
<div>In essence, ISR enables you to instruct Next.js to update the cache for a specific page and use the most recent published content.</div>
<div>Now the question arises: How do we know when the content in the content graph has been updated and returns the freshest content? This is where webhooks come into play. You can configure a webhook to inquire about content revalidation from the provided API when it's ready. The link to configure the webhook can be found here:</div>
<div><a href="https://docs.developers.optimizely.com/platform-optimizely/v1.4.0-optimizely-graph/reference/create-webhookhandler">Optimizely Webhook Configuration</a></div>
<div> </div>
<div>On this page, you need to choose the type of authentication. I opted for Header HMAC authentication (epi-hmac xxx), and the token used here is also employed for fetching unpublished content in draft mode. The token is a combination of AppKey and AppSecret. You can learn more about it <a href="https://kunalshetye.com/posts/optimizely-graph-using-appkey-appsecret/">here</a></div>
<div>.</div>
<div>Before configuring the webhook, we need to create an API route that will handle the revalidation logic. For us, this route is <strong>`api/revalidate`</strong>.</div>
<div>
<pre class="language-javascript"><code>import { optimizely } from "@/api/optimizely";
import { revalidatePath } from "next/cache";
export async function POST(request: Request) {
const { searchParams } = new URL(request.url);
const webhookSecret = searchParams?.get("cg_webhook_secret");
if (webhookSecret !== process.env.CG_WEBHOOK_SECRET) {
return new Response("Invalid credentials", {
status: 401,
});
}
const requestJson = await request.json();
const docId = requestJson?.data?.docId || "";
if (docId && docId.includes("Published")) {
const [guid] = docId.split("_");
try {
const { data, errors } = await optimizely.GetContentByGuid({ guid });
if (errors) {
console.error(errors);
return new Response("Error fetching content", { status: 500 });
}
const url = data?.Content?.items?.[0]?.RelativePath;
if (!url) {
return new Response("Page Not Found", { status: 400 });
}
const normalizeUrl = url.startsWith("/") ? url : `/${url}`;
// Someone published new changes, flush the cache
console.log(`Flushing cache for: ${normalizeUrl}`);
revalidatePath(normalizeUrl);
} catch (error) {
console.error("Error processing webhook:", error);
return new Response("Internal Server Error", { status: 500 });
}
}
return new Response("OK", {
status: 200,
});
}</code></pre>
</div>
<div><strong> </strong></div>
<div><strong>Tip: </strong></div>
<div>To locally test the webhook communication, you can use ngrok tunneling. It will proxy your http://localhost:3000 to https and generate a randomly assigned link. After creating it, you can use that link for webhook configuration.</div>
<div> </div>
<h4>Webhook Configuration:</h4>
<div><img src="https://hatimeriacom-strapi.s3.eu-central-1.amazonaws.com/webhook_configuration_b746ac9b29.png" width="600" alt="Webhook configuration" height="645" style="display: block; margin-left: auto; margin-right: auto;" /></div>
<div><strong></strong></div>
<div><strong> </strong></div>
<div><strong>Example:</strong></div>
<div>
<pre class="language-javascript"><code>Disabled: false
url: <your-url>/api/revalidate?cg_webhook_secret=<secret from env>
method: POST</code></pre>
</div>
<div><strong> </strong></div>
<div><strong>Example `requestJson`:</strong></div>
<div>
<pre class="language-javascript"><code>{
timestamp: '2023-11-24T13:48:58.1384743+00:00',
tenantId: 'bd1b0e79e7cf4548b046292ce22ea898',
type: { subject: 'doc', action: 'updated' },
data: { docId: '7b08c7d5-7585-47e5-add7-5822da68c3ce_en_Published' }
}
flushing cache for: /en</code></pre>
</div>
<div> </div>
<div>Unfortunately, the webhook only returns the <strong>`GUID`</strong> and not the <strong>`RelativePath`</strong>. To extract the path, we need to query the Optimizely graph for information about the page based on the GUID.</div>
<div> </div>
<div>
<pre class="language-javascript"><code>query GetContentByGuid($guid: String) {
Content(where: { ContentLink: { GuidValue: { eq: $guid } } }) {
items {
RelativePath
}
}
}</code></pre>
</div>
<div>All these components allow us to generate the entire site during production builds and return all pages from the cache. When we publish a new change to one of the pages, we only revalidate that specific page, enabling a seamless and efficient process.</div>
<div> </div>
<h3>Pros and Cons of Optimizely Graph and Next.js Headless Solution</h3>
<table>
<tbody>
<tr>
<td>Pros </td>
<td>Cons </td>
</tr>
<tr>
<td>Performance (SSR, SSG, ISR)</td>
<td>Additional layer of complexity</td>
</tr>
<tr>
<td>Uses Edge</td>
<td>No support for Commerce</td>
</tr>
<tr>
<td>Uses latest technology</td>
<td>A more expensive solution than the traditional Hybrid in terms of development</td>
</tr>
<tr>
<td>Attractive for devs</td>
<td>Publishing content in CMS does not equate to an immediate change on the site</td>
</tr>
<tr>
<td>Good SEO</td>
<td></td>
</tr>
<tr>
<td>A single source for content CMS -> web, mobile app…</td>
<td></td>
</tr>
</tbody>
</table>
<div> </div>
<div>Optimizely Graph has several advantages, including improved performance through server-side rendering (SSR) and static site generation (SSG). It leverages edge computing technology and utilizes the latest technology stack, making it attractive for developers. It also offers good search engine optimization (SEO) capabilities and provides a centralized content management system (CMS) for managing content across web and mobile applications.</div>
<div> </div>
<div>However, there are some drawbacks to consider. Implementing the solution adds an additional layer of complexity to the development process. It currently lacks support for commerce functionality. The development costs can be higher compared to traditional hybrid solutions. It's also important to note that publishing content in the CMS does not guarantee immediate changes on the website.</div>
<div> </div>
<div>In summary, while the solution offers performance benefits, modern technology and a centralized content management system, it also presents complexities, limitations in commerce support and higher development costs. It's crucial to assess these factors based on specific requirements before deciding on its adoption.</div>
<h2>Best Practices and Tips</h2>
<h4><strong>Avoid using Apollo Client</strong></h4>
<div>Avoid using Apollo Client in your Next.js project. While it is a powerful GraphQL client, Next.js provides robust native support for fetching data using the built-in <strong>`fetch`</strong> function. Apollo Client, being feature-rich, can introduce unnecessary overhead to your project.</div>
<div> </div>
<div>Next.js comes with several built-in features that make it well-suited for handling GraphQL requests. It provides extensive capabilities, such as cache tags and revalidation, making it unnecessary to rely on external heavyweight libraries like Apollo Client.</div>
<div> </div>
<div>By sticking to Next.js native features and optimizing your GraphQL requests using the built-in fetch function, you can keep your project lightweight, efficient, and well-aligned with the framework's best practices.</div>
<h4><strong> </strong></h4>
<h4><strong>Use Tailwind CSS</strong></h4>
<div>I recommend using <a href="https://tailwindcss.com/">Tailwind CSS</a> as it provides an optimal solution tailored for Next.js. Tailwind CSS generates all styles during the build process into a single file, which is typically very small (in our Next.js projects, the CSS file is around 16-30kb). This approach enhances performance and aligns well with Next.js conventions.</div>
<div> </div>
<h4><strong>UI Librabry</strong></h4>
<div>If you're in search of a UI library with versatile components, we highly recommend choosing <a href="https://ui.shadcn.com/">Shadcn UI</a>. It has proven to be an excellent choice in several of our projects. Shadcn UI offers extensive customization options and has consistently met all our requirements.</div>
<div><a href="https://www.hatimeria.com/blog/article/react-and-shadcn-ui-a-match-made-in-heaven">More about shadcn</a></div>
<div> </div>
<h4><strong>Use Codegen</strong></h4>
<div>Utilizing code generation alongside Optimizely Graph can save a significant amount of time. This is because you won't need to manually type page or block types. Code generation also creates TypeScript methods for interacting with Optimizely Graph. All you have to do is create a GraphQL query and run the code generation command. Notably, you can pass your custom fetcher, enabling customization according to your requirements.</div>
<h2>Conclusion</h2>
<div>In conclusion, the integration of Optimizely Graph and Next.js offers a powerful solution for building scalable headless applications. By leveraging GraphQL capabilities through Optimizely Graph, developers can structure and interconnect content within Optimizely CMS in a more efficient and intuitive manner. This is complemented by Next.js, a React-based frontend framework that enables the creation of performant and SEO-friendly web applications, supporting both static and dynamic rendering.</div>
<div> </div>
<div>The symbiotic relationship between Optimizely Graph and Next.js allows for the crafting of dynamic headless experiences. This includes features like draft modes, On-Page Editing, static site generation, and efficient page revalidation through webhooks.</div>
<div> </div>
<div>In summary, the Optimizely Graph and Next.js integration provides a robust foundation for developing scalable, performant, and SEO-friendly headless applications, with the flexibility to adapt to various use cases and requirements.</div>2023-11-27T15:52:03.0000000ZBlog postHow to configure Alpine.js and Tailwind CSS with Optimizely<h2><span style="font-weight: 400;">Why Tailwind CSS and Alpine.js </span></h2>
<p><span style="font-weight: 400;">Let's start with a definition for those who haven't heard of these technologies yet: </span></p>
<ul>
<li>Tailwind CSS<span style="font-weight: 400;"> is a popular utility-first CSS framework that provides a set of predefined classes to quickly build responsive and customizable user interfaces.</span><span style="font-weight: 400;"><br /></span></li>
<li>Alpine.js<span style="font-weight: 400;"> is a lightweight (</span><a href="https://bundlephobia.com/package/alpinejs@3.12.1">14.1kB</a><span style="font-weight: 400;">) JavaScript framework that focuses on providing a declarative syntax for building interactive web interfaces. </span></li>
</ul>
<p><span style="font-weight: 400;">When we create an online store we usually don't need much logic for generic pages where we display the blocks themselves. In this case using frameworks like Vue.js or React is unnecessary because .net is a modern technology and we can do everything without using JavaScript just by using the styles in Razor pages. With that approach we have a great chance of passing Core Web Vitals without worrying about them, because of the much smaller amount of JavaScript loaded. For dynamic pages with a lot of logic, like the cart or checkout page, we already need a framework in which the frontend developer can communicate with the backend. Here we wanted to choose the lightest possible framework that would provide responsiveness and a global state.</span></p>
<p><span style="font-weight: 400;">At Hatimeria we have extensive experience implementing the Hyva theme for Magento-based stores, so we decided to use our knowledge in projects with Optimizely.</span></p>
<p><span style="font-weight: 400;">The combination of Alpine.js and Tailwind CSS works very well there, so we decided to check out these technologies with Optimizely, since on paper it seems to be a very good combination and, in addition, it works well for many stores that run on Magento.</span></p>
<p><span style="font-weight: 400;">In summary, we chose Alpine.js and Tailwind CSS because we use a small amount of JavaScript and only load the styles that are used in our application, resulting in faster loading times and better performance.</span></p>
<h2><span style="font-weight: 400;">Pros and cons of Tailwind CSS</span></h2>
<p><span style="font-weight: 400;">Here are some pros and cons of using Tailwind CSS:</span></p>
<p><span style="font-weight: 400;">Pros:</span></p>
<ul>
<li><strong>Rapid Development</strong><span style="font-weight: 400;">: Tailwind CSS allows developers to quickly build user interfaces by utilizing pre-defined utility classes. This speeds up the development process as you don't have to write custom CSS styles from scratch.</span></li>
<li><strong>Highly Customizable</strong><span style="font-weight: 400;">: Tailwind CSS provides a vast number of utility classes that can be combined and customized to create unique designs. It offers extensive control over spacing, typography, colors and more, allowing you to easily match your design requirements.</span></li>
<li><strong>Performance</strong><span style="font-weight: 400;">: Tailwind CSS is designed to be highly optimized for production use. By utilizing utility classes, you can eliminate unused CSS and keep the final bundle size minimal, resulting in faster page load times.</span><span style="font-weight: 400;"><br /></span></li>
<li><strong>Easy Maintenance</strong><span style="font-weight: 400;">: the CSS file contains the styles that are used in the files and automatically removes unnecessary styles without having to worry that removing a particular line will break the layout somewhere. </span></li>
</ul>
<p><span style="font-weight: 400;">Cons:</span></p>
<ul>
<li><strong>Conflicts in Git</strong>: <span style="font-weight: 400;">can occur when multiple developers make changes to the same class and all styles are written in a single line. These conflicts may become more frequent with larger teams. However, the good news is that resolving them is not difficult. </span><span style="font-weight: 400;"><br /></span></li>
<li><strong>Styles added from the admin panel may not work</strong>: <span style="font-weight: 400;">Tailwind classes may not work if the added classes in the admin panel are not previously used in the code and added in the generated CSS file.</span><span style="font-weight: 400;"><br /></span></li>
<li><strong>Learning Curve</strong><span style="font-weight: 400;">: While the utility-first approach of Tailwind CSS offers great flexibility, it can have a steep learning curve, especially for developers who are accustomed to traditional CSS frameworks.</span></li>
<li><strong>Lack of Free Design Constraints</strong><span style="font-weight: 400;">: While Tailwind CSS provides flexibility, it doesn't impose any design constraints or opinionated free components out of the box (That option is a paid extra). This means you'll have to design and structure your UI components from scratch, which may require additional effort and expertise.</span></li>
</ul>
<h2><span style="font-weight: 400;">Pros and cons of Alpine js</span></h2>
<p><span style="font-weight: 400;">Here are some pros and cons of using Alpine.js:</span></p>
<p><span style="font-weight: 400;">Pros:</span></p>
<ul>
<li><strong>Lightweight</strong><span style="font-weight: 400;">: Alpine.js is designed to be lightweight (</span><a href="https://bundlephobia.com/package/alpinejs@3.12.1">14.1kB</a>) <span style="font-weight: 400;">and has a small footprint. It adds only a minimal amount of JavaScript code to your project, resulting in faster load times and improved performance.</span></li>
<li><strong>Familiar Syntax</strong><span style="font-weight: 400;"><strong>:</strong> The syntax of Alpine.js is similar to popular frontend frameworks like Vue.js, making it easier for developers already familiar with these frameworks to quickly grasp Alpine.js and start building interactive components. So far I have written frontend in Vue.js version 2, writing js is virtually identical, the only difference is that we do not have key words like data, methods, mounted, etc everything is written on one level. It took me several hours to change from Vue.js to Alpine.j</span><span style="font-weight: 400;"><br /></span></li>
<li><strong>Stable</strong>:<span style="font-weight: 400;"> The </span><a href="https://github.com/alpinejs/alpine/issues"><span style="font-weight: 400;">repository on github</span></a><span style="font-weight: 400;"> looks very good as it has 23.8k stars and 0 issues at the moment. In comparison, the </span><a href="https://github.com/vuejs/core"><span style="font-weight: 400;">Vue.js repository</span></a><span style="font-weight: 400;"> has 37.7k stars and 615 issues.</span><span style="font-weight: 400;"><br /></span></li>
<li><strong>Progressive Enhancement</strong><span style="font-weight: 400;">: Alpine.js follows a progressive enhancement approach, which means you can progressively add interactivity to your project without requiring a complete rewrite. You can selectively apply Alpine.js to specific elements and enhance the user experience without disrupting the existing functionality.</span></li>
</ul>
<p><span style="font-weight: 400;">Cons:</span></p>
<ul>
<li><strong>Learning Curve</strong><span style="font-weight: 400;">: While Alpine.js has a relatively low learning curve compared to more complex frameworks, developers who are new to JavaScript frameworks may still need to invest some time in understanding its concepts and syntax.</span></li>
<li><strong>Community and Ecosystem</strong><span style="font-weight: 400;">: Alpine.js has a growing community, but it may not have the same level of community support or extensive ecosystem as larger frameworks. This means that finding pre-built components or libraries specifically tailored for Alpine.js might be more challenging.</span></li>
<li><strong>JavaScript Dependency</strong><span style="font-weight: 400;">: Alpine.js relies on JavaScript to function, which means that if a user has disabled JavaScript in their browser, the interactivity provided by Alpine.js will not be available. This can be a limitation for projects that require broad accessibility or compatibility with older browsers.</span></li>
</ul>
<h2><span style="font-weight: 400;">Tailwind CSS in a .NET Optimizely project</span></h2>
<h3><span style="font-weight: 400;">Configuration</span></h3>
<p><span style="font-weight: 400;"><br /></span><span style="font-weight: 400;">We did the whole configuration based on an </span><a href="https://khalidabuhakmeh.com/install-tailwind-css-with-aspnet-core#install-tailwind"><span style="font-weight: 400;">article</span></a><span style="font-weight: 400;"> and the </span><a href="https://tailwindcss.com/docs/installation/using-postcss"><span style="font-weight: 400;">Tailwind documentation</span></a><span style="font-weight: 400;">, so to sum up here are the steps to follow:</span></p>
<p><span style="font-weight: 400;">Run the command </span><strong>npm init -y</strong><span style="font-weight: 400;"> to quickly and automatically create a package.json file for the project. Flag </span>-y<span style="font-weight: 400;"> means "yes", which means that all configuration questions will be automatically accepted with default values.</span><span style="font-weight: 400;"><br /><br /></span></p>
<pre class="language-javascript"><code>npm init -y</code></pre>
<h4></h4>
<p><span style="font-weight: 400;">Next, install Tailwind and its dependencies.</span><span style="font-weight: 400;"><br /></span></p>
<pre class="language-javascript"><code>npm install -D tailwindcss@latest postcss@latest autoprefixer@latest
</code></pre>
<p><span style="font-weight: 400;"> </span></p>
<h4><span style="font-weight: 400;">Run the Tailwind initialization command `</span>npx tailwind init -p<span style="font-weight: 400;">`</span></h4>
<pre class="language-javascript"><code>npx tailwind init -p</code></pre>
<p><span style="font-weight: 400;">After running the Tailwind initialization command, two files should be generated: </span><strong>postcss.config.js</strong><span style="font-weight: 400;"> and</span> t<strong>ailwind.config.js</strong><br /><br /></p>
<p><span style="font-weight: 400;">Here is the configuration used in our project for those files:</span></p>
<p><strong>postcss.config.js</strong><span style="font-weight: 400;"><br /></span></p>
<pre class="language-javascript"><code>module.exports = {
plugins: {
tailwindcss: { config: './tailwindcss-config.js' },
'postcss-import': {},
'tailwindcss/nesting': {},
autoprefixer: {},
...(process.env.NODE_ENV === 'production' ? { cssnano: {} } : {}),
},
};</code></pre>
<p><strong></strong></p>
<p><strong>t</strong><strong>ailwind.config.js</strong></p>
<pre class="language-javascript"><code>/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
'./Views/**/*.cshtml',
'./Features/**/*.cshtml',
'./Features/CMS/ContentAreaRenderer/ContentAreaItemRenderer.cs',
],
theme: {
extend: {},
},
variants: {
extend: {},
},
plugins: [],
};</code></pre>
<p><span style="font-weight: 400;">Tailwind CSS works by scanning all of your HTML files, JavaScript components and any other templates for class names, generating the corresponding styles and then writing them to a static CSS file. So it is even possible to generate CSS from a .cs file, when you add the paths in the content. In our project, in the </span>ContentAreaItemRenderer.cs<span style="font-weight: 400;"> file, we added support for </span><a href="https://docs.developers.optimizely.com/content-management-system/docs/display-options"><span style="font-weight: 400;">Display Options</span></a><span style="font-weight: 400;"> and the corresponding classes for the selected option. </span></p>
<pre class="language-javascript"><code> private static string GetCssClassForTag(string tagName)
{
if (string.IsNullOrEmpty(tagName))
{
return string.Empty;
}
return tagName.ToLowerInvariant() switch
{
ContentAreaTags.FullWidth => "w-full",
ContentAreaTags.WideWidth => "w-full lg:w-8/12",
ContentAreaTags.HalfWidth => "w-full md:w-6/12",
ContentAreaTags.NarrowWidth => "w-full md:w-6/12 lg:w-4/12",
_ => string.Empty,
};
}</code></pre>
<p><span style="font-weight: 400;">Add the </span>@tailwind<span style="font-weight: 400;"> directives for each of Tailwind’s layers to your main CSS file.</span></p>
<p><strong>site.css</strong></p>
<pre class="language-css"><code>/*! @import */
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";</code></pre>
<h4></h4>
<h4><span style="font-weight: 400;">Add build scripts for Tailwind in </span>package.json</h4>
<pre class="language-javascript"><code>"scripts": {
"css:build": "npx tailwindcss -i ./wwwroot/css/site.css -o ./wwwroot/css/output.css --minify",
"css:watch": "npx tailwindcss -i ./wwwroot/css/site.css -o ./wwwroot/css/output.css --watch"
},</code></pre>
<p><strong>css:build</strong><span style="font-weight: 400;"> is a script for production with minify output</span><span style="font-weight: 400;"><br /></span><strong>css:watch</strong><span style="font-weight: 400;"> is a script for development </span><br /><br /></p>
<p><span style="font-weight: 400;">Then in your project </span><strong>.csproj</strong> <span style="font-weight: 400;">add the configured npm commands to run automatically every time you build a project</span></p>
<pre class="language-csharp"><code> <Target Name="Tailwind" BeforeTargets="Build" Condition="'$(Configuration)' == 'Debug'">
<Exec Command="npm run css:watch" />
</Target>
<Target Name="Tailwind" BeforeTargets="Build" Condition="'$(Configuration)' == 'Release'">
<Exec Command="npm run css:build" />
</Target></code></pre>
<h4></h4>
<h4><span style="font-weight: 400;">Add import for the generated CSS file in View Layout</span></h4>
<pre class="language-javascript"><code><head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
@Html.CanonicalLink()
@Html.AlternateLinks()
@Html.RequiredClientResources("Header")
<link rel="stylesheet" href="~/css/output.css" />
</head></code></pre>
<p><strong></strong></p>
<p><strong>Cache</strong><strong></strong></p>
<p><span style="font-weight: 400;">In a development environment, the provided code will function correctly if the "disabled cache" checkbox is selected in the network tab of the DevTools. However, in a production project, it's important to handle versioning of the CSS file to ensure that users are not using an outdated version.</span></p>
<p><span style="font-weight: 400;">Here's an improved version of the code that addresses this issue by generating an ID based on the latest modification of the CSS file:</span></p>
<pre class="language-csharp"><code>namespace Web.Infrastructure
{
public static class CssHelper
{
private static string? _cssFileVersion;
public static string GetCssFileVersion()
{
if (_cssFileVersion == null)
{
var cssFilePath = "wwwroot/css/output.css";
var cssFileLastModified = File.GetLastWriteTime(cssFilePath);
_cssFileVersion = cssFileLastModified.ToString("yyyyMMddHHmmss");
}
return _cssFileVersion;
}
}
}</code></pre>
<p><br />Updated import:</p>
<pre class="language-javascript"><code>@using Web.Infrastructure;
<link rel="stylesheet" href="~/css/output.css?v=@CssHelper.GetCssFileVersion()" /></code></pre>
<p><span style="font-weight: 400;">In this code, you can adjust the </span><strong>cssFilePath </strong><span style="font-weight: 400;">variable to the appropriate path of your CSS file. The </span>File.<strong>GetLastWriteTime()</strong><span style="font-weight: 400;"> method retrieves the last modification time of the CSS file.</span></p>
<p><span style="font-weight: 400;">By calling the </span><strong>CssHelper.GetCssFileVersion()</strong><span style="font-weight: 400;"> method in your CSHTML file as </span><strong>@CssHelper.GetCssFileVersion()</strong><span style="font-weight: 400;">, you will get a unique ID based on the last edit of the CSS file. This ensures the effective handling of caching and guarantees that users receive the latest version of the CSS file in a production environment.</span></p>
<p><span style="font-weight: 400;">Start using Tailwind in your CSHTML</span></p>
<p><span style="font-weight: 400;"><br /><img src="https://www.hatimeria.com/_next/image?url=https%3A%2F%2Fhatimeriacom-strapi.s3.eu-central-1.amazonaws.com%2Fpasted_image_0_7c735af76d.png&w=828&q=75" width="828" alt="" height="124" /><br /></span></p>
<h3></h3>
<h3><span style="font-weight: 400;">Hot Reload </span></h3>
<p><span style="font-weight: 400;">There is a package on NuGet called </span><a href="https://www.nuget.org/packages/Tailwind.Extensions.AspNetCore/1.0.0-beta3"><span style="font-weight: 400;">Tailwind.Extensions.AspNetCore</span></a><span style="font-weight: 400;"> that allows hot reload to work with CSHTML and makes life easier for frontend developers. It is worth noting that it is in beta version, but during development we didn't encounter major problems with its use except for the problems described in Limitation. </span></p>
<h3><span style="font-weight: 400;">Configuration </span></h3>
<p><span style="font-weight: 400;">In order to configure hot reloading you need to follow the steps below:</span></p>
<h3><span style="font-weight: 400;">Instal package </span></h3>
<pre class="language-csharp"><code>dotnet add package Tailwind.Extensions.AspNetCore --version 1.0.0-beta3</code></pre>
<h3></h3>
<h3><span style="font-weight: 400;">Add configuration in Startup.cs</span></h3>
<p><span style="font-weight: 400;">Add the npm command you configured in </span><strong>package.json</strong><span style="font-weight: 400;"> to run Tailwind in development mode. In our application it is </span>“<strong>css:watch</strong>”<span style="font-weight: 400;">.</span></p>
<pre class="language-csharp"><code>using Tailwind;
namespace Web;
public class Startup
{
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.RunTailwind("css:watch");
}
}
}</code></pre>
<p><span style="font-weight: 400;">The </span><strong>RunTailwind</strong><span style="font-weight: 400;"><strong> </strong>method gets two parameters:</span></p>
<ul>
<li><span style="font-weight: 400;">string npmScript, </span></li>
<li><span style="font-weight: 400;">string workingDir = "./"</span></li>
</ul>
<p><span style="font-weight: 400;">The default value for </span>workingDir <span style="font-weight: 400;">is </span>“./”<span style="font-weight: 400;"> so we omitted it in Startup.cs</span></p>
<h3><span style="font-weight: 400;">Limitation </span></h3>
<p><span style="font-weight: 400;">There is a </span><a href="https://github.com/Practical-ASP-NET/Tailwind.Extensions.AspNetCore#known-issues"><span style="font-weight: 400;">known issue</span></a><span style="font-weight: 400;"> with using Visual Studio 2022 because hot reloading does not always work. We also experienced this when building our application. </span></p>
<p><span style="font-weight: 400;">So a much better solution is to use the</span><span style="font-weight: 400;"> command</span></p>
<pre class="language-csharp"><code>dotnet watch run</code></pre>
<p><span style="font-weight: 400;">and make changes in Visual Studio Code. </span></p>
<h2><span style="font-weight: 400;">Alpine js in a .net Optimizely project</span></h2>
<h3><span style="font-weight: 400;">Configuration </span></h3>
<p><span style="font-weight: 400;">Adding Alpine.js to a project is very simple. We chose the </span><a href="https://alpinejs.dev/essentials/installation#from-a-script-tag"><span style="font-weight: 400;">from a script tag</span></a><span style="font-weight: 400;"> way to add in the head tag. In Views we added it once in the Layout: </span></p>
<pre class="language-javascript"><code><head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
@Html.CanonicalLink()
@Html.AlternateLinks()
@Html.RequiredClientResources("Header")
<link rel="stylesheet" href="~/css/output.css" />
//alpine import
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.12.1/dist/cdn.min.js"></script>
// import api helper
<script src="~/js/store/api.js"></script>
</head></code></pre>
<p><span style="font-weight: 400;">After that we have full access to all the features offered by Alpine.js.</span></p>
<h3><span style="font-weight: 400;">Writing code</span></h3>
<p><span style="font-weight: 400;">In the case of Alpine.js, we have two options for writing code in CSHTML files or creating new js files and adding them in a script tag. In our project we decided to add simple functionality like opening, closing the mobile menu in CSHTML, and all logic for checkout or the cart in JavaScript files. Since it had more than 300 lines of code we wanted to separate the code in CSHTML to make it more readable. In these files we add the whole logic to the Alpine store and in CSHTML we added the appropriate import in the script tag.</span></p>
<h4><span style="font-weight: 400;">CSHTML example</span></h4>
<pre class="language-javascript"><code><div
class="z-20 order-2 sm:order-1 lg:order-2 navigation lg:hidden"
x-data="initMenuMobile()">
<div
class="bg-container-lighter"
x-bind:class="{'h-screen overflow-x-hidden overflow-y-auto fixed top-0 left-0 w-full' : open}"
x-on:keydown.window.escape="open=false"
x-on:toggle-mobile-menu.window="open = !open">
//mobile menu
</div>
</div>
<script>
'use strict';
function initMenuMobile() {
return {
open: false,
}
}
</script>
</code></pre>
<h4></h4>
<h4><span style="font-weight: 400;">JavaScript files</span></h4>
<p><strong>checkout.js</strong></p>
<pre class="language-javascript"><code>document.addEventListener('alpine:init', () => {
Alpine.store('checkout', {
isLoading: false,
//...
});
});</code></pre>
<p><strong>checkout.cshtml</strong></p>
<pre class="language-javascript"><code>@model CheckoutPage;
<script defer src="~/js/store/checkout.js"></script>
<section x-data class="py-12 relative flex flex-col lg:flex-row lg:gap-10" x-bind:class="{'blur pointer-events-none' : $store.checkout.isLoading }">
</section></code></pre>
<p><strong>$store.checkout.isLoading</strong> <span style="font-weight: 400;">is a boolean responsible for loading a state on action like adding a shipping address, choosing a shipping method etc… </span></p>
<p><span style="font-weight: 400;">The </span><a href="https://alpinejs.dev/globals/alpine-store"><span style="font-weight: 400;">Alpine Store</span></a><span style="font-weight: 400;"> can be used for Vue.js mixins. For example in our application we use fetch and every time we would have to repeat the logic for it by attaching anti-forgery token in headers. Instead we created an API helper file for fetch. </span></p>
<p><br /><strong>api.js</strong></p>
<pre class="language-javascript"><code>document.addEventListener('alpine:init', () => {
Alpine.store('apiHelper', {
REQUEST_VERIFICATION_TOKEN: document.querySelector('[name=__RequestVerificationToken]')
? document.querySelector('[name=__RequestVerificationToken]').getAttribute('value')
: '',
async fetch(options) {
const requestOptions = {
url: options.url || '',
method: options.method || 'GET',
body: options.body || null,
headers: options.headers || {},
prefix: options.prefix || `/api/${window.GLOBAL_LOCALE}/`
};
try {
const response = await fetch(`${window.location.origin}${requestOptions.prefix}${requestOptions.url}`, {
method: requestOptions.method,
headers: {
'Content-Type': 'application/json',
...requestOptions.headers,
RequestVerificationToken: this.REQUEST_VERIFICATION_TOKEN,
},
body: requestOptions.body,
});
return response;
} catch (error) {
// handle exception
}
},
});
});</code></pre>
<p><strong>checkout.js</strong></p>
<pre class="language-javascript"><code> async loadShippingMethods() {
try {
this.startLoading();
const options = {
url: 'checkout/shipping/methods',
};
const response = await Alpine.store('apiHelper').fetch(options);
if (response.status !== 200) {
this.initErrorMessages();
}
const data = await response.json();
this.shippingMethods = data || [];
this.stopLoading();
} catch (error) {
this.initErrorMessages();
}
},</code></pre>
<p><span style="font-weight: 400;">With this approach when we want to change something in fetch like adding default headers, we can do it in one place.</span></p>
<h4><span style="font-weight: 400;">Cache</span></h4>
<pre class="language-javascript"><code><script defer src="~/js/store/checkout.js"></script></code></pre>
<p><span style="font-weight: 400;">The code provided may lead to production issues due to the lack of versioning for the JavaScript file. This can cause caching problems for end users. To address this, we have a couple of potential solutions:</span></p>
<p><span style="font-weight: 400;"><strong></strong></span></p>
<p><span style="font-weight: 400;"><strong>Option 1:</strong> Implement versioning based on the last edit of each file, similar to how we handle styles. This way, each file will have a unique version, allowing for effective cache management.</span></p>
<p><span style="font-weight: 400;"><strong>Option 2: </strong>Alternatively, we can opt for a uniform versioning approach where all files receive the same version number. In this case, we would need to increment the version number with each deployment. One possible approach is to base the version on the Assembly of Startup.cs or Program.cs.</span></p>
<p><span style="font-weight: 400;">By implementing one of these solutions, we can ensure proper cache handling and mitigate potential issues in production caused by outdated JavaScript files.</span></p>
<p><span style="font-weight: 400;">Let me know your thoughts on which option would work best for your project.</span></p>
<h3><strong></strong></h3>
<h3><strong>Limitations of Alpine.js in .net</strong></h3>
<p><span style="font-weight: 400;">In CSHTML files, symbols like "@" and ":" have special meanings in Razor's syntax. Therefore, using shorthand syntax for x-bind (using ":") and x-on (using "@") in CSHTML files will not work as expected. These symbols are reserved for Razor's syntax and cannot be used as shorthand syntax for Alpine.js directives in CSHTML files.</span></p>
<p><span style="font-weight: 400;">To ensure proper usage, developers should remember not to use shorthand syntax for x-bind and x-on in CSHTML files and instead use the full syntax provided by Alpine.js for these directives. This will prevent conflicts with Razor's syntax and ensure the correct interpretation of the code.</span></p>
<p><span style="font-weight: 400;">Nevertheless, there is also the option to use the shorthand syntax for x-on via “@@”, but this can lead to confusion and in our case we chose not to use shorthand syntax. </span></p>
<h2><span style="font-weight: 400;">Results - performance</span></h2>
<p><span style="font-weight: 400;">We expected good results on Lighthouse but didn't think they would be that good without thinking too much about performance when developing the application. Every page on mobile and desktop achieves a score of </span><strong>100</strong><span style="font-weight: 400;"><strong>.</strong> </span></p>
<p><img src="https://www.hatimeria.com/_next/image?url=https%3A%2F%2Fhatimeriacom-strapi.s3.eu-central-1.amazonaws.com%2F1_b1144a335f.png&w=828&q=75" width="805" alt="performance-100" height="757" /><br /><br /></p>
<p><span style="font-weight: 400;"> <img src="https://www.hatimeria.com/_next/image?url=https%3A%2F%2Fhatimeriacom-strapi.s3.eu-central-1.amazonaws.com%2F2_ae1cdd482b.png&w=828&q=75" width="819" alt="perofrmance-100" height="761" /></span></p>
<p><span style="font-weight: 400;">In summary, my transition from Vue.js to Alpine.js was very smooth and the performance results are much better.</span></p>
<h2><span style="font-weight: 400;">Conclusion</span></h2>
<p><span style="font-weight: 400;">If you have encountered any problems while trying to set up your project I will be more than happy to help you resolve them. </span></p>
<p><br /><br /></p>2023-10-12T13:51:13.0000000ZBlog post