Akismet: Introducing the official Akismet JavaScript SDK
Spam doesn’t care what your site runs on. A contact form on a Next.js app or a comment box on a Cloudflare Worker gets the same junk a WordPress blog does. After the PHP SDK in June, we’re excited to release the official JavaScript SDK for Akismet.
Who is this for?
@automattic/akismet is a TypeScript client for the Akismet API. It’s for developers adding spam protection to comments, contact forms, or signups in a JavaScript backend.
- It covers the whole Akismet API.
- It runs on Node.js 22 and later, and on Bun, Deno, and Cloudflare Workers.
- It comes with typechecked examples for Express, Fastify, Hono, Next.js, and plain
node:http.
A two-minute quick start
npm install @automattic/akismet
Then check each submission in the route that receives it. In a Next.js app, that’s app/api/comments/route.ts:
import {
Akismet, AkismetError, ContentType, SpamVerdict,
} from '@automattic/akismet';
const akismet = new Akismet({
apiKey: process.env.AKISMET_API_KEY!,
site: 'https://your-site.com',
isTest: process.env.AKISMET_TEST_MODE === '1', // Disable learning
});
export async function POST(request: Request) {
const { comment, name, email } = await request.json();
try {
const result = await akismet
.forRequest(request, { trustedProxyHops: 1 })
.check({
body: comment,
authorName: name,
authorEmail: email,
type: ContentType.Comment,
});
console.log(result.verdict);
if (result.verdict === SpamVerdict.Discard) {
// Akismet is sure it's spam. Drop it.
} else if (result.isSpam) {
// Hold it for moderation.
} else {
// Publish it.
}
} catch (error) {
if (!(error instanceof AkismetError)) throw error;
// Safe to log: the SDK redacts the API key.
console.error(error);
// Akismet failed or rejected the input. Hold it for review.
}
return new Response(null, { status: 202 });
}
site is the front page of your site. Check out the README for details on how the the Client IP is configured.
Every framework follows the same flow: check the submission, then act on the verdict. You can check out some examples for Express, Fastify, Hono, node:http, and Next.js Server Actions.
What’s in 1.0
- Spammers can’t fake their IP. Trust only the headers from proxies you allow.
- Your API key stays out of your logs. Log every error worry free.
- You can tell Akismet when it gets one wrong. Keep the content you checked and its verdict, when a moderator finds missed spam or a false positive, report it. Akismet learns from those reports, check out the README for how.
Get started
The Akismet SDK is open source under the MIT license.
- Find it on npm.
- Read the code and docs on GitHub.
- Building with an AI coding agent? Tell it to read the
SKILL.mdthat ships with@automattic/akismet.
You’ll need an Akismet API key. The Personal plan is name-your-price for personal sites and blogs, and commercial sites need a paid plan sized to their traffic. Your code stays the same whichever plan you’re on.
Found a bug, or something that doesn’t fit your stack? Open an issue on GitHub.