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 Builds

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.

Note

If you don’t already have it, you’ll need the dotenv package to load environment variables from your local .env file. Install it by running the following:

npm install dotenv

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

astro.config.js

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
      copy, // custom copy overrides (see below)
    }),
    // ...the rest of your configuration details.
  ],
});

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

Note

For more information about all the parameters you can configure, check out the documentation on fetch options.

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.

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.

Note

This prop will be ignored if you’re building your site via batch. Scroll down for information on that.

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

Overriding Copy for Batch Builds

If you’re generating your site with a batch build (see above for more information), you’ll need to pass your custom copy into the jamComments plugin configuration:

export default defineConfig({
  integrations: [
    jamComments({
      domain: process.env.JAM_COMMENTS_DOMAIN,
      apiKey: process.env.JAM_COMMENTS_API_KEY,

      // Custom copy:
      copy: {
        commentPlaceholder: "Write something",
        submitButton: "Send it!",
        namePlaceholder: "Ur Mom",
        emailPlaceholder: "[email protected]",
      }
    }),
    // ...the rest of your configuration details.
  ],
});

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.