Installation
How to install the Opinly SDK
Before you can use the Opinly SDK, ensure you have an existing Next.js project running on your own domain. This integration does not require a separate CMS or markdown file management.
1. Install the SDK packages
pnpm add @opinly/backend @opinly/next
yarn add @opinly/backend @opinly/next
npm i @opinly/backend @opinly/next
- @opinly/backend: A Node-compatible client for fetching blog content and metadata.
- @opinly/next: React components, hooks, and utilities for integrating with Next.js routing and ISR.
2. Configure your environment variables
Create an environment file (e.g. .env.local
) at your project root and add the following variables:
# API key
# Found in Settings > Developers tab
OPINLY_API_KEY="<YOUR_API_KEY>"
3. Next.js Configuration
Add this to your next.config.js
(or next.config.mjs
) to proxy image requests through the Opinly CDN:
Make sure to replace the following values with your own:
companyName
cdnNamespace
siteUrl
import type { NextConfig } from 'next'
import { withOpinlyConfig } from '@opinly/next/utils/with-opinly-config'
const nextConfig: NextConfig = {
// ... your next config ...
};
const withOpinly = withOpinlyConfig({
// The path where the blog will be hosted. Make sure it matches the blog route in your app
blogPath: '/blog',
// The path where the images will be hosted. Make sure it does not overlap with your own assets
imagesPath: '/images',
// The name of the company. This is used in the metadata
companyName: 'REPLACE ME',
// The namespace of the CDN. This is used to identify the images in the CDN
// This is found in the Settings > Developers tab
cdnNamespace: 'REPLACE-ME-xxxxxx',
// The URL of the site. This is used in the metadata. Do not include a trailing slash.
siteUrl: 'https://REPLACE-ME.com',
})
module.exports = withOpinly(nextConfig);
4. Client Setup
To interact with the Opinly backend, you need to initialize the SDK client. Create a new file at clients/opinly.ts
(or .js
):
// clients/opinly.ts
import { createOpinlyClient } from '@opinly/backend'
export const opinly = createOpinlyClient({
fetch: (input, init) => fetch(input, { ...init, cache: 'force-cache' }), // Leverage Next.js ISR caching
})
Parameters:
Option | Description |
---|---|
apiKey | Optional. Your Opinly API key. Default set from OPINLY_API_KEY env var if not provided. |
fetch | Optional. Custom fetch wrapper; example uses cache: 'force-cache' for ISR performance. |
Make sure to restart your dev server after setting environment variables so
process.env
is populated.
5. Blog Integration
Integrate the Opinly SDK into your Next.js application to serve SEO-optimized blog content under your configured prefix (e.g. /blog
).
Add a file at app/blog/[[...slug]]/page.tsx
:
Make sure that the blog/
route matches the OPINLY_BLOG_PREFIX
in your environment variables.
// app/blog/[[...slug]]/page.tsx
import { OpinlyBlog } from '@opinly/next';
import { generateOpinlyMetadata } from '@opinly/next/utils/generate-metadata';
import { opinly } from '@/clients/opinly';
import { ResolvingMetadata } from 'next';
// Revalidate every 3 days (in seconds)
export const revalidate = 60 * 60 * 24 * 3;
export async function generateMetadata(
{ params }: { params: Promise<{ slug: string[] }> },
parent: ResolvingMetadata
) {
return generateOpinlyMetadata(opinly, params, parent);
}
export default async function BlogPage(
{ params, searchParams }:
{ params: Promise<{ slug: string[] }>; searchParams: Promise<{ page?: string }> }
) {
const [slugParams, qp] = await Promise.all([params, searchParams]);
const blog = await opinly.content.blog({ params: slugParams });
return <OpinlyBlog blog={blog} client={opinly} searchParams={qp} />;
}
6. Sitemap Generation
Use the Next.js built-in MetadataRoute API to automatically generate a sitemap.xml
that combines your core site routes with all of your Opinly-powered blog posts.
In your app
directory, add app/sitemap.ts
(or .js
) with the following:
import { opinly } from '@/clients/opinly'
import type { MetadataRoute } from 'next'
export const revalidate = 259200 // 3 days
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
// Fetch records for all blog posts under your configured prefix
const blogSiteMapRecords = await opinly.content.sitemapRecords({
blogUrl: `${process.env.OPINLY_SITE_URL}${process.env.OPINLY_BLOG_PREFIX}`,
})
return [
// Spread in all dynamically generated blog entries
...blogSiteMapRecords,
]
}
Next Steps
Congratulations— youve successfully integrated the Opinly SDK into your Next.js site!
- Create blog posts in the Opinly Dashboard under Content.
- Schedule your posts to publish automatically on your desired cadence.
- Visit
/blog
to see your blog posts appear.
Once your posts are published, they’ll be indexed by search engines—driving targeted SEO traffic directly to your Next.js application. Happy blogging!