SQD Module Template: Agent's Guide

This guide shows how to clone the template, build any Untitled UI app, wire API routes, use Supabase in the API server, publish to npm, and consume the package elsewhere.

NPM package: https://www.npmjs.com/package/@thesquad-components/sqd-module-template

Rules (must follow)

• UI assets: Only use Untitled UI icons from https://www.untitledui.com/resources/icons.
• UI components: Only use Untitled UI React components from https://www.untitledui.com/react/components.
• API calls: All API calls must go through your own Next.js API routes (no direct calls from components).
• Module key header: Every outbound API request must include x-sqd-module-key.
• Env vars: Use the existing Vercel env vars (do not create new keys).
• Supabase: Use the @supabase/supabase-js library for all Supabase access.
• API safety: Keep secrets server-only. Never call external APIs directly from the client. Your Next.js API routes should be the only place that sends x-sqd-module-key.
• Private access: Packages are private to @thesquad-components and should be published with restricted access.

Supabase example (API server route)

import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

// inside your route handler:
const { data, error } = await supabase.from("your_table").select("*");

Beginner Guide: Clone, Build, Publish, Use (with API + Supabase)

1) Clone both repos

Single command (both at once):

git clone https://github.com/sis-thesqd/sqd-module-template && git clone https://github.com/sis-thesqd/sqd-api-server

Or two commands:

git clone https://github.com/sis-thesqd/sqd-module-template
git clone https://github.com/sis-thesqd/sqd-api-server

2) Install dependencies (in the template repo)

cd sqd-module-template
npm install

3) Rename the package

• Open package.json
• Set name to @thesquad-components/your-app-name
• Save

4) Build your Untitled UI app

• Open src
• Replace starter components with your UI
• Keep exports consistent for imports later

5) Create API routes for all API calls (module repo)

• Create files under src/app/api/<your-route>/route.ts
• Each route should call your backend (or any external API) and return JSON
• Always include x-sqd-module-key when calling outward
• Do not expose keys in client code or query params. This prevents people from reusing calls found in network logs.

6) Supabase setup for API server routes

Available env vars in sqd-api-server:

• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY
• SQD_MODULE_KEY (use this one; already set in Vercel)

In your API server route, create a Supabase client using those env vars, then run queries and return JSON.

7) Test locally

npm run dev
npm run build

8) Publish to npm under @thesquad-components

If you are not logged in, run npm login first.

Replace the token in the command below, then run:

export NPM_TOKEN=npm_....
npm publish --access restricted

9) Use it in another app

npm install @thesquad-components/your-app-name

import { YourComponent } from "@thesquad-components/your-app-name";

10) Update later

• Make changes
• Bump version in package.json (use semantic versioning: MAJOR.MINOR.PATCH)
• Publish again with the same token flow:

export NPM_TOKEN=npm_....
npm publish --access restricted

NPM account + org access (@thesquad-components)

Create an npm account

1. Go to https://www.npmjs.com/signup
2. Create an account and verify your email
3. Enable 2FA (recommended)

Request access to the @thesquad-components org (owned by Jacob)

Send Jacob the following:

• Your npm username
• The email on your npm account
• Confirmation you enabled 2FA

Once added to @thesquad-components, you can publish under the scope.