One of the arguments against the Jamstack approach for building websites is that developing features gets complex and often requires a number of other services. Take commenting, for example. To set up commenting for a Jamstack site, you often need a third-party solution such as Disqus, Facebook, or even just a separate database service. That third-party solution usually means your comments live disconnected from their content.
When we use third-party systems, we have to live with the trade-offs of using someone else’s code. We get a plug-and-play solution, but at what cost? Ads displayed to our users? Unnecessary JavaScript that we can’t optimize? The fact that the comments content is owned by someone else? These are definitely things worth considering.
Monolithic services, like WordPress, have solved this by having everything housed under the same application. What if we could house our comments in the same database and CMS as our content, query it in the same way we query our content, and display it with the same framework on the front end?
It would make this particular Jamstack application feel much more cohesive, both for our developers and our editors.
Let’s make our own commenting engine
In this article, we’ll use Next.js and Sanity.io to create a commenting engine that meets those needs. One unified platform for content, editors, commenters, and developers.
Why Next.js?
Next.js is a meta-framework for React, built by the team at Vercel. It has built-in functionality for serverless functions, static site generation, and server-side rendering.
For our work, we’ll mostly be using its built-in “API routes” for serverless functions and its static site generation capabilities. The API routes will simplify the project considerably, but if you’re deploying to something like Netlify, these can be converted to serverless functions or we can use Netlify’s next-on-netlify package.
It’s this intersection of static, server-rendered, and serverless functions that makes Next.js a great solution for a project like this.
Why Sanity?
Sanity.io is a flexible platform for structured content. At its core, it is a data store that encourages developers to think about content as structured data. It often comes paired with an open-source CMS solution called the Sanity Studio.
We’ll be using Sanity to keep the author’s content together with any user-generated content, like comments. In the end, Sanity is a content platform with a strong API and a configurable CMS that allows for the customization we need to tie these things together.
Setting up Sanity and Next.js
We’re not going to start from scratch on this project. We’ll begin by using the simple blog starter created by Vercel to get working with a Next.js and Sanity integration. Since the Vercel starter repository has the front end and Sanity Studio separate, I’ve created a simplified repository that includes both.
We’ll clone this repository, and use it to create our commenting base. Want to see the final code? This “Starter” will get you set up with the repository, Vercel project, and Sanity project all connected.
The starter repo comes in two parts: the front end powered by Next.js, and Sanity Studio. Before we go any further, we need to get these running locally.
To get started, we need to set up our content and our CMS for Next to consume the data. First, we need to install the dependencies required for running the Studio and connecting to the Sanity API.
# Install the Sanity CLI globally
npm install -g @sanity/cli
# Move into the Studio directory and install the Studio's dependencies
cd studio
npm installOnce these finish installing, from within the /studio directory, we can set up a new project with the CLI.
# If you're not logged into Sanity via the CLI already
sanity login
# Run init to set up a new project (or connect an existing project)
sanity initThe init command asks us a few questions to set everything up. Because the Studio code already has some configuration values, the CLI will ask us if we want to reconfigure it. We do.
From there, it will ask us which project to connect to, or if we want to configure a new project.
We’ll configure a new project with a descriptive project name. It will ask us to name the “dataset” we’re creating. This defaults to “production” which is perfectly fine, but can be overridden with whatever name makes sense for your project.
The CLI will modify the file ~/studio/sanity.json with the project’s ID and dataset name. These values will be important later, so keep this file handy.
For now, we’re ready to run the Studio locally.
# From within /studio
npm run startAfter the Studio compiles, it can be opened in the browser at http://localhost:3333.
At this point, it makes sense to go into the admin and create some test content. To make the front end work properly, we’ll need at least one blog post and one author, but additional content is always nice to get a feel for things. Note that the content will be synced in real-time to the data store even when you’re working from the Studio on localhost. It will become instantly available to query. Don’t forget to push publish so that the content is publicly available.
Once we have some content, it’s time to get our Next.js project running.
Getting set up with Next.js
Most things needed for Next.js are already set up in the repository. The main thing we need to do is connect our Sanity project to Next.js. To do this, there’s an example set of environment variables set in /blog-frontent/.env.local.example. Remove .example from that file and then we’ll modify the environment variables with the proper values.
We need an API token from our Sanity project. To create this value, let’s head over to the Sanity dashboard. In the dashboard, locate the current project and navigate to the Settings → API area. From here, we can create new tokens to use in our project. In many projects, creating a read-only token is all we need. In our project, we’ll be posting data back to Sanity, so we’ll need to create a Read+Write token.
When clicking “Add New Token,” we receive a pop-up with the token value. Once it’s closed, we can’t retrieve the token again, so be sure to grab it!
This string goes in our .env.local file as the value for SANITY_API_TOKEN. Since we’re already logged into manage.sanity.io , we can also grab the project ID from the top of the project page and paste it as the value of NEXT_PUBLIC_SANITY_PROJECT_ID. The SANITY_PREVIEW_SECRET is important for when we want to run Next.js in “preview mode”, but for the purposes of this demo, we don’t need to fill that out.
We’re almost ready to run our Next front-end. While we still have our Sanity Dashboard open, we need to make one more change to our Settings → API view. We need to allow our Next.js localhost server to make requests.
In the CORS Origins, we’ll add a new origin and populate it with the current localhost port: http://localhost:3000. We don’t need to be able to send authenticated requests, so we can leave this off When this goes live, we’ll need to add an additional Origin with the production URL to allow the live site to make requests as well.
Our blog is now ready to run locally!
# From inside /blog-frontend
npm run devAfter running the command above, we now have a blog up and running on our computer with data pulling from the Sanity API. We can visit http://localhost:3000 to view the site.
Creating the schema for comments
To add comments to our database with a view in our Studio, we need to set up our schema for the data.
To add our schema, we’ll add a new file in our /studio/schemas directory named comment.js. This JavaScript file will export an object that will contain the definition of the overall data structure. This will tell the Studio how to display the data, as well as structuring the data that we will return to our frontend.
In the case of a comment, we’ll want what might be considered the “defaults” of the commenting world. We’ll have a field for a user’s name, their email, and a text area for a comment string. Along with those basics, we’ll also need a way of attaching the comment to a specific post. In Sanity’s API, the field type is a “reference” to another type of data.
If we wanted our site to get spammed, we could end there, but it would probably be a good idea to add an approval process. We can do that by adding a boolean field to our comment that will control whether or not to display a comment on our site.
export default {
name: 'comment',
type: 'document',
title: 'Comment',
fields: [
{
name: 'name',
type: 'string',
},
{
title: 'Approved',
name: 'approved',
type: 'boolean',
description: "Comments won't show on the site without approval"
},
{
name: 'email',
type: 'string',
},
{
name: 'comment',
type: 'text',
},
{
name: 'post',
type: 'reference',
to: [
{type: 'post'}
]
}
],
}After we add this document, we also need to add it to our /studio/schemas/schema.js file to register it as a new document type.
import createSchema from 'part:@sanity/base/schema-creator'
import schemaTypes from 'all:part:@sanity/base/schema-type'
import blockContent from './blockContent'
import category from './category'
import post from './post'
import author from './author'
import comment from './comment' // <- Import our new Schema
export default createSchema({
name: 'default',
types: schemaTypes.concat([
post,
author,
category,
comment, // <- Use our new Schema
blockContent
])
})
Once these changes are made, when we look into our Studio again, we’ll see a comment section in our main content list. We can even go in and add our first comment for testing (since we haven’t built any UI for it in the front end yet).
An astute developer will notice that, after adding the comment, the preview our comments list view is not very helpful. Now that we have data, we can provide a custom preview for that list view.
Adding a CMS preview for comments in the list view
After the fields array, we can specify a preview object. The preview object will tell Sanity’s list views what data to display and in what configuration. We’ll add a property and a method to this object. The select property is an object that we can use to gather data from our schema. In this case, we’ll take the comment’s name, comment, and post.title values. We pass these new variables into our prepare() method and use that to return a title and subtitle for use in list views.
export default {
// ... Fields information
preview: {
select: {
name: 'name',
comment: 'comment',
post: 'post.title'
},
prepare({name, comment, post}) {
return {
title: `${name} on ${post}`,
subtitle: comment
}
}
}
}
}The title will display large and the subtitle will be smaller and more faded. In this preview, we’ll make the title a string that contains the comment author’s name and the comment’s post, with a subtitle of the comment body itself. You can configure the previews to match your needs.
The data now exists, and our CMS preview is ready, but it’s not yet pulling into our site. We need to modify our data fetch to pull our comments onto each post.
Displaying each post’s comments
In this repository, we have a file dedicated to functions we can use to interact with Sanity’s API. The /blog-frontend/lib/api.js file has specific exported functions for the use cases of various routes in our site. We need to update the getPostAndMorePosts function in this file, which pulls the data for each post. It returns the proper data for posts associated with the current page’s slug, as well as a selection of new posts to display alongside it.
In this function, there are two queries: one to grab the data for the current post and one for the additional posts. The request we need to modify is the first request.
Changing the returned data with a GROQ projection
The query is made in the open-source graph-based querying language GROQ, used by Sanity for pulling data out of the data store. The query comes in three parts:
- The filter – what set of data to find and send back
*[_type == "post" && slug.current == $slug] - An optional pipeline component — a modification to the data returned by the component to its left
| order(_updatedAt desc) - An optional projection — the specific data elements to return for the query. In our case, everything between the brackets (
{}).
In this example, we have a variable list of fields that most of our queries need, as well as the body data for the blog post. Directly following the body, we want to pull all the comments associated with this post.
In order to do this, we create a named property on the object returned called 'comments' and then run a new query to return the comments that contain the reference to the current post context.
The entire filter looks like this:
*[_type == "comment" && post._ref == ^._id && approved == true]The filter matches all documents that meet the interior criteria of the square brackets ([]). In this case, we’ll find all documents of _type == "comment". We’ll then test if the current post’s _ref matches the comment’s _id. Finally, we check to see if the comment is approved == true.
Once we have that data, we select the data we want to return using an optional projection. Without the projection, we’d get all the data for each comment. Not important in this example, but a good habit to be in.
curClient.fetch(
`*[_type == "post" && slug.current == $slug] | order(_updatedAt desc) {
${postFields}
body,
'comments': *[_type == "comment" && post._ref == ^._id && approved == true]{
_id,
name,
email,
comment,
_createdAt
}
}`,
{ slug }
)
.then((res) => res?.[0]),Sanity returns an array of data in the response. This can be helpful in many cases but, for us, we just need the first item in the array, so we’ll limit the response to just the zero position in the index.
Adding a Comment component to our post
Our individual posts are rendered using code found in the /blog-frontend/pages/posts/[slug].js file. The components in this file are already receiving the updated data in our API file. The main Post() function returns our layout. This is where we’ll add our new component.
Comments typically appear after the post’s content, so let’s add this immediately following the closing </article> tag.
// ... The rest of the component
</article>
// The comments list component with comments being passed in
<Comments comments={post?.comments} />We now need to create our component file. The component files in this project live in the /blog-frontend/components directory. We’ll follow the standard pattern for the components. The main functionality of this component is to take the array passed to it and create an unordered list with proper markup.
Since we already have a <Date /> component, we can use that to format our date properly.
# /blog-frontend/components/comments.js
import Date from './date'
export default function Comments({ comments = [] }) {
return (
<>
<h2 className="mt-10 mb-4 text-4xl lg:text-6xl leading-tight">Comments:</h2>
<ul>
{comments?.map(({ _id, _createdAt, name, email, comment }) => (
<li key={_id} className="mb-5">
<hr className="mb-5" />
<h4 className="mb-2 leading-tight"><a href={`mailto:${email}`}>{name}</a> (<Date dateString={_createdAt}/>)</h4>
<p>{comment}</p>
<hr className="mt-5 mb-5" />
</li>
))
</ul>
</>
)
}Back in our /blog-frontend/pages/posts/[slug].js file, we need to import this component at the top, and then we have a comment section displayed for posts that have comments.
import Comments from '../../components/comments'We now have our manually-entered comment listed. That’s great, but not very interactive. Let’s add a form to the page to allow users to submit a comment to our dataset.
Adding a comment form to a blog post
For our comment form, why reinvent the wheel? We’re already in the React ecosystem with Next.js, so we might as well take advantage of it. We’ll use the react-hook-form package, but any form or form component will do.
First, we need to install our package.
npm install react-hook-formWhile that installs, we can go ahead and set up our Form component. In the Post component, we can add a <Form /> component right after our new <Comments /> component.
// ... Rest of the component
<Comments comments={post.comments} />
<Form _id={post._id} />Note that we’re passing the current post _id value into our new component. This is how we’ll tie our comment to our post.
As we did with our comment component, we need to create a file for this component at /blog-frontend/components/form.js.
export default function Form ({_id}) {
// Sets up basic data state
const [formData, setFormData] = useState()
// Sets up our form states
const [isSubmitting, setIsSubmitting] = useState(false)
const [hasSubmitted, setHasSubmitted] = useState(false)
// Prepares the functions from react-hook-form
const { register, handleSubmit, watch, errors } = useForm()
// Function for handling the form submission
const onSubmit = async data => {
// ... Submit handler
}
if (isSubmitting) {
// Returns a "Submitting comment" state if being processed
return <h3>Submitting comment…</h3>
}
if (hasSubmitted) {
// Returns the data that the user submitted for them to preview after submission
return (
<>
<h3>Thanks for your comment!</h3>
<ul>
<li>
Name: {formData.name} <br />
Email: {formData.email} <br />
Comment: {formData.comment}
</li>
</ul>
</>
)
}
return (
// Sets up the Form markup
)
}This code is primarily boilerplate for handling the various states of the form. The form itself will be the markup that we return.
// Sets up the Form markup
<form onSubmit={handleSubmit(onSubmit)} className="w-full max-w-lg" disabled>
<input ref={register} type="hidden" name="_id" value={_id} />
<label className="block mb-5">
<span className="text-gray-700">Name</span>
<input name="name" ref={register({required: true})} className="form-input mt-1 block w-full" placeholder="John Appleseed"/>
</label>
<label className="block mb-5">
<span className="text-gray-700">Email</span>
<input name="email" type="email" ref={register({required: true})} className="form-input mt-1 block w-full" placeholder="your@email.com"/>
</label>
<label className="block mb-5">
<span className="text-gray-700">Comment</span>
<textarea ref={register({required: true})} name="comment" className="form-textarea mt-1 block w-full" rows="8" placeholder="Enter some long form content."></textarea>
</label>
{/* errors will return when field validation fails */}
{errors.exampleRequired && <span>This field is required</span>}
<input type="submit" className="shadow bg-purple-500 hover:bg-purple-400 focus:shadow-outline focus:outline-none text-white font-bold py-2 px-4 rounded" />
</form>In this markup, we’ve got a couple of special cases. First, our <form> element has an onSubmit attribute that accepts the handleSubmit() hook. That hook provided by our package takes the name of the function to handle the submission of our form.
The very first input in our comment form is a hidden field that contains the _id of our post. Any required form field will use the ref attribute to register with react-hook-form’s validation. When our form is submitted we need to do something with the data submitted. That’s what our onSubmit() function is for.
// Function for handling the form submission
const onSubmit = async data => {
setIsSubmitting(true)
setFormData(data)
try {
await fetch('/api/createComment', {
method: 'POST',
body: JSON.stringify(data),
type: 'application/json'
})
setIsSubmitting(false)
setHasSubmitted(true)
} catch (err) {
setFormData(err)
}
}This function has two primary goals:
- Set state for the form through the process of submitting with the state we created earlier
- Submit the data to a serverless function via a
fetch()request. Next.js comes withfetch()built in, so we don’t need to install an extra package.
We can take the data submitted from the form — the data argument for our form handler — and submit that to a serverless function that we need to create.
We could post this directly to the Sanity API, but that requires an API key with write access and you should protect that with environment variables outside of your front-end. A serverless function lets you run this logic without exposing the secret token to your visitors.
Submitting the comment to Sanity with a Next.js API route
In order to protect our credentials, we’ll write our form handler as a serverless function. In Next.js, we can use “API routes” to create serverless function. These live alongside our page routes in the /blog-frontent/pages directory in the api directory. We can create a new file here called createComment.js.
To write to the Sanity API, we first need to set up a client that has write permissions. Earlier in this demo, we set up a read+write token and put it in /blog-frontent/.env.local. This environment variable is already in use in a client object from /blog-frontend/lib/sanity.js. There’s a read+write client set up with the name previewClient that uses the token to fetch unpublished changes for preview mode.
At the top of our createClient file, we can import that object for use in our serverless function. A Next.js API route needs to export its handler as a default function with request and response arguments. Inside our function, we’ll destructure our form data from the request object’s body and use that to create a new document.
Sanity’s JavaScript client has a create() method which accepts a data object. The data object should have a _type that matches the type of document we wish to create along with any data we wish to store. In our example, we’ll pass it the name, email, and comment.
We need to do a little extra work to turn our post’s _id into a reference to the post in Sanity. We’ll define the post property as a reference and give the_id as the _ref property on this object. After we submit it to the API, we can return either a success status or an error status depending on our response from Sanity.
// This Next.js template already is configured to write with this Sanity Client
import {previewClient} from '../../lib/sanity'
export default async function createComment(req, res) {
// Destructure the pieces of our request
const { _id, name, email, comment} = JSON.parse(req.body)
try {
// Use our Client to create a new document in Sanity with an object
await previewClient.create({
_type: 'comment',
post: {
_type: 'reference',
_ref: _id,
},
name,
email,
comment
})
} catch (err) {
console.error(err)
return res.status(500).json({message: `Couldn't submit comment`, err})
}
return res.status(200).json({ message: 'Comment submitted' })
}Once this serverless function is in place, we can navigate to our blog post and submit a comment via the form. Since we have an approval process in place, after we submit a comment, we can view it in the Sanity Studio and choose to approve it, deny it, or leave it as pending.
Take the commenting engine further
This gets us the basic functionality of a commenting system and it lives directly with our content. There is a lot of potential when you control both sides of this flow. Here are a few ideas for taking this commenting engine further.
- Create and send an email notification for a new message with SendGrid or other mail services.
- Section the Sanity Studio API to show Approved, Unapproved, and Pending comments with Sanity’s Structure Builder.
- Implement spam protection with Google’s invisible reCAPTCHA.
- Integrate with Gravatar when a comment is saved.
The post How to Create a Commenting Engine with Next.js and Sanity appeared first on CSS-Tricks.
You can support CSS-Tricks by being an MVP Supporter.
source https://css-tricks.com/how-to-create-a-commenting-engine-with-next-js-and-sanity/
No comments:
Post a Comment