@submitator/badges: the npm package for your directory badges

Ask an AI to check it

You do not have to take our word for any of this. Ask an assistant to read this page and the package's source, and to tell you what it finds.

What it does

1. 1

   Fetches your badges on your server. It asks api.submitator.com for your project's wall and keeps it in memory. It refreshes the wall in the background every 60 seconds by default, while your pages keep using the copy they have. A server with no copy yet, or only an expired one, waits 2 seconds at most by default.

2. 2

   Checks them. Our signature first, then every badge: see What it checks first, below.

3. 3

   Renders them with your framework. React on Next.js, Vue on Nuxt, Svelte on SvelteKit, an Astro component on Astro, or an escaped HTML string on any other Node server. The badges are in the HTML your server sends, which is what directories and our own check read.

4. 4

   Keeps them current. On a page your server renders on request, new badges show up within minutes, with nothing to redeploy. From day one it shows your Featured on Submitator badge; directory badges join it as we submit you to directories that ask for one, and so do badges you add in the app.

The request carries your project ID, the package version and your framework's name, and nothing about your visitors. At most once an hour we note when your server fetched and with which version and framework, to show your install on Configure Badges. Like every request to our API, each one is also written to our server log with your server's IP address, which our host keeps for up to 30 days.

What it never does

• No calls from your visitors' browsers.

  Only your server talks to us. Run in a browser, the package's fetch returns nothing and sends nothing.

• No HTML from our servers.

  We send data; the package builds every element itself, and every value is escaped, by your framework or by the package.

• No script tag.

  The scrolling strip moves with CSS alone, pauses on hover and keyboard focus, and stands still for visitors who ask for reduced motion. With Next.js Server Components (App Router) and Astro, the badge component ships no JavaScript to the browser. On Nuxt, SvelteKit and the Next.js Pages Router it hydrates with the rest of your app, like any component.

• No cookies.

  Its request carries no cookie and nothing about your visitors, and our answer sets none.

• No secrets, no settings.

  It reads no secrets and no configuration. Of your environment variables it reads only NODE_ENV and NEXT_RUNTIME: to mark requests from development servers, and to spot Next.js, so it can use Next's cache.

• No broken pages.

  If our API is slow, down or answers something unexpected, your server keeps its last good copy or renders the page without badges.

What your visitors' browsers load: each badge image, from the address in its embed code (usually the directory's own site). The Featured on Submitator badge is drawn inline and loads nothing.

What it checks first

Every wall we send is signed with an Ed25519 key. The package carries two public keys, the one we sign with and a backup we keep offline, and checks the signature before it reads anything else. A wall that is unsigned, changed on the way or signed by anyone else is refused, and no option changes that for our API: publicKeys, which swaps the keys for a local or test backend, is refused for any address on api.submitator.com. Then it checks that:

• the wall is for your project ID and has not expired (each one is valid for 7 days);
• each badge is made only of links, images, text and simple shapes (a, img, span, svg, path and circle), with attributes from a fixed list: no class, no id and no event handlers;
• every link and image address starts with http:// or https:// (a few directories still use http): never javascript:, data: or a relative path;
• each inline style passes declaration by declaration: no url(), image-set(), @import, expression(), behavior or position: fixed, no comments and no characters that could break out of the style;
• shapes sit only inside an svg, and no link sits inside another link;
• the response, the wall and each badge stay within fixed limits: 1 MiB per response, 200 badges per wall, 300 nodes and 16 levels of nesting per badge.

A badge that fails is left out, and the rest show. A wall that fails is never shown: your server keeps its last good copy until that copy expires. The package's own CSS is one style element and a style attribute on the wall's outer element, which repeats the wall's containment (position: relative, overflow: hidden, contain: paint, isolation: isolate), so no badge draws outside the wall even where a Content-Security-Policy blocks the style element. The only styles that come from our servers are the badges' inline styles, checked as above.

What the package adds to a badge, and nothing else: loading="lazy" on images that do not set it, a directory badge's name as alt where its image has none, tabindex="-1" on the links of the strip's hidden repeat, and a span around badges you add yourself. It never changes a link's or an image's address, or a link's rel or target.

The full rules, with every limit, are in CONTRACT.md in the repository.

Your project ID

The package needs one value: your project ID. It is public on purpose: it already sits in the link of your Featured on Submitator badge, and anyone can read your badges with it, which is the point of a badge. It cannot change your project, see your account or spend anything, so there is no key to hide, rotate or revoke.

Configure Badges in the app shows the snippet for your framework with your ID filled in.

Open source

The package is MIT licensed and has no dependencies: React, Vue, Svelte and Astro come from your own project. Each TypeScript file in the repository's src folder is compiled to one readable JavaScript file in dist, with no bundling and no minifying, and the Svelte and Astro components ship as their own source files, so you can read every file you install in your node_modules. Read the code on GitHub, or the exact files you would install from npm.

npm i @submitator/badges

// app/page.tsx: your homepage, a Server Component (no "use client")import { SubmitatorBadges } from "@submitator/badges/react"; export default function Home() {  return (    <footer>      <SubmitatorBadges project="YOUR_PROJECT_ID" />    </footer>  );}

// app/badges.tsx: render <Badges /> in your homepage footerimport { cacheLife } from "next/cache";import { SubmitatorBadges } from "@submitator/badges/react"; export async function Badges() {  "use cache";  cacheLife("minutes");  return <SubmitatorBadges project="YOUR_PROJECT_ID" />;}

// pages/index.tsximport { fetchWall, type Wall } from "@submitator/badges";import { BadgeWall } from "@submitator/badges/react"; export async function getStaticProps() {  return { props: { wall: await fetchWall({ project: "YOUR_PROJECT_ID" }) }, revalidate: 60 };} export default function Home({ wall }: { wall: Wall | null }) {  return (    <footer>      <BadgeWall wall={wall} />    </footer>  );}

// server/api/submitator-badges.get.tsimport { fetchWall } from "@submitator/badges"; export default defineEventHandler(async () => ({  wall: await fetchWall({ project: "YOUR_PROJECT_ID", framework: "nuxt" }),}));

<!-- components/SubmitatorBadges.vue: render it in your homepage footer --><script setup lang="ts">import { BadgeWall } from "@submitator/badges/vue"; const { data } = await useFetch("/api/submitator-badges");</script> <template>  <BadgeWall v-if="data?.wall" :wall="data.wall" /></template>

// src/routes/+layout.server.ts (merge into your load if you have one)import { fetchWall } from "@submitator/badges"; export async function load() {  return { wall: await fetchWall({ project: "YOUR_PROJECT_ID", framework: "sveltekit" }) };}

<!-- src/routes/+layout.svelte --><script lang="ts">  import { BadgeWall } from "@submitator/badges/svelte";   let { data, children } = $props();</script> {@render children()} <footer>  {#if data.wall}    <BadgeWall wall={data.wall} />  {/if}</footer>

---// src/components/Footer.astroimport { SubmitatorBadges } from "@submitator/badges/astro";--- <footer>  <SubmitatorBadges project="YOUR_PROJECT_ID" /></footer>

import { fetchWall, wallToHtml } from "@submitator/badges"; const wall = await fetchWall({ project: "YOUR_PROJECT_ID" });const badgesHtml = wallToHtml(wall); // "" when there is no wall; every value is escaped// Print badgesHtml inside your footer, in the HTML your server sends.

curl -sL 'https://your-site.com' | grep -cE 'data-sbm-ref="?YOUR_PROJECT_ID'

Caches, CDNs and Content-Security-Policy

Directories read the HTML your homepage serves, so whatever keeps a copy of that HTML decides how soon new badges show.

Static builds. Astro's default output, Next.js with output: "export", SvelteKit pages with prerender and nuxi generate fetch the badges when they build, and only then. Render your homepage on request, or rebuild after you add directories.

CDN and page caches. If a CDN or a page cache stores your homepage (Cloudflare's Cache Everything, a long edge TTL, a caching plugin), keep that copy for 60 seconds or less, or purge it after you add directories. curl -sI 'https://your-site.com' shows the age and cache-control headers of the copy it serves.

Content-Security-Policy. img-src must allow https:, because badge images load from each directory's site, and http: too if a directory serves its image over http. The wall uses style attributes and one style element: allow both with 'unsafe-inline' in style-src, or keep style-src strict, add style-src-attr 'unsafe-inline' and give the package your nonce with its nonce option. Nothing changes for script-src: the package adds no script.

Last updated October 31, 2026