Astro Integration

Astro is a modern framework that bills itself as being great for building “fast, content-focused websites.” Two of its primary selling points include a framework-agnostic approach to building sites, as well as the “islands” architecture it’s been pioneering.

These instructions assume you’ve already created a JamComments account as well as a site within that account. If you haven’t, learn more about that process on the Getting Started page.

Installation & Configuration

Install the plugin with npm (or whatever package manager you’re using):

npm install @jam-comments/astro`

After doing so, you can configure it by setting the following environment variables in your site:

Syntax	Description
`JAM_COMMENTS_DOMAIN`	The domain for your site as configured in your account. Don’t include the protocol (“https”).
`JAM_COMMENTS_API_KEY`	The API generated in your account settings.
`JAM_COMMENTS_ENVIRONMENT`	The environment JamComments will use to determine if it should render dummy comments. If this isn’t set, `NODE_ENV` is used.

For more detailed instructions on setting environment variables with Astro, see their documentation here. Once your site is deployed, it’s recommended to manage these values with your hosting provider. For example, here’s how you’d manage them with Vercel.

Usage

Import the JamComments component, place it where you’d like comments to render. You’re done!

import JamComments from '@jam-comments/astro';
---

// The rest of your markup...

<JamComments />

If you’d like to more explicitly configure the integration, you can also pass the following props to the component, rather than relying on environment variables:

import JamComments from '@jam-comments/astro';

// Astro.request docs:
// https://docs.astro.build/en/reference/api-reference/#astrorequest
const path = new URL(Astro.request.url).pathname
---

// The rest of your markup...

<JamComments
  path={path}
  apiKey="123ABC"
  domain="whatever.com"
  environment="production"
  tz="America/Chicago"
  schema={jsonStringOrJavaScriptObject}
/>

Improving Build Performance with Batch Requests

By default, the plugin will fetch markup & comments for a page individually. This is a great approach for if you’re dynamically rendering pages, but statically generated sites could see a slight bump in build times.

To help mitigate this, set up the JamComments in your Astro configuration file after importing it from @jam-comments/astro/config. You’ll need to explicitly pass in the environment variables you’ve already saved.

Here’s an example of how your configuration might look:

import { defineConfig } from "astro/config";
import { jamComments } from "@jam-comments/astro/config";
import "dotenv/config";

export default defineConfig({
  integrations: [
    jamComments({
      domain: process.env.JAM_COMMENTS_DOMAIN,
      apiKey: process.env.JAM_COMMENTS_API_KEY,
      environment, // `production` or `development` // optional
      timezone, // any valid timezone identifier // optional
    }),
    // ...the rest of your configuration details.
  ],
});

This will cause all comment data to be fetched in batches up front, saving you some build time.

Overriding Copy in UI

The JamComments UI comes with its own set of basic copy for its components (submission confirmation, submit button text, etc.). Many of this copy can be overridden with the copy prop.

Property	Where It Appears	Default
`confirmationMessage`	In the success banner after submitting a comment.	”Comment successfully submitted!”
`submitButton`	In the comment submission button.	”Submit”
`namePlaceholder`	In the “name” input.	(empty)
`emailPlaceholder`	In the “email” input.	(empty)
`commentPlaceholder`	In the comment textarea.	”Write something in plain text or Markdown…”
`writeTab`	In the tab for composing a comment.	”Write”
`previewTab`	In the tab for previewing a comment.	”Preview”
`authButton`	In the link for signing in or registering.	”Log In or Register”
`logOutButton`	In the link for logging out.	”Log Out”

You can pass these values in the copy prop:

<JamComments
  schema={postSchema}
  copy={{
    commentPlaceholder: "Write something",
    submitButton: "Send it!",
    namePlaceholder: "Ur Mom",
    emailPlaceholder: "[email protected]",
  }}
/>

Automated Schema Generation

Out of the box, JamComments will automatically generate structured data (JSON-LD) for your pages, as long as a BlogPosting or Article entity already exists on the page. This configuration-free approach generates the data client-side with JavaScript — an approach well-supported by Google.

However, if you’d like that data to be server-rendered, you can do so by passing your JSON string or JavaScript object as a prop:

import JamComments from '@jam-comments/astro';

const { schemaJson } = Astro.props;
---

// The rest of your markup...

<JamComments
  schema={schemaJson}
/>

When schema is passed like this, the plugin will render the full object with comments into the HTML. Just remember to not render it yourself if you use this feature, as to avoid duplicate records appearing on the page.

Setting a Date Format

The default date format for comments is 'm/d/Y. If you’re from another country, that might be weird. So, you can customize it by using the dateFormat prop. Note that the format must follow PHP’s DateTime standards.

<!-- Thursday, October 31, 2024 -->
<JamComments dateFormat="l, F j, Y" />

Contributions

The source for this plugin is open to contributions. If you have a bug fix or idea for improvement, leave a pull request or issue in the GitHub repository.