@sonordev/agency-site-kit

v0.4.2

Published

2 days ago

Premium portfolio showcase components for Sonor-powered agency websites

0High
0Medium
0Low

uptrademedia

ramseydeal

@sonordev/agency-site-kit

Premium portfolio showcase for Sonor-powered agency sites. Renders full case study pages (hero, challenges, results, tech stack, testimonials, live metrics and more) from portfolio data managed in the Sonor dashboard, with the agency's own brand tokens applied.

Built for the Next.js App Router. The case study renderer is a genuine React Server Component — section content ships as HTML, and only the animated sections send JavaScript to the browser.

Install

pnpm add @sonordev/agency-site-kit @sonordev/site-kit

@sonordev/site-kit is a peer dependency (it provides the shared Sonor data plane). One env var in .env.local:

SONOR_API_KEY=sonor_xxxxxxxx_xxxxxxxxxxxx

The key is read server-side only and never reaches the browser. There's no NEXT_PUBLIC_ variant and no project ID — the API resolves the project from the key.

Image optimization

Portfolio images render through next/image. Allow the hosts Sonor serves images from in your next.config:

images: {
  formats: ['image/avif', 'image/webp'],
  remotePatterns: [
    // Screenshots + uploads (Supabase Storage)
    { protocol: 'https', hostname: '**.supabase.co', pathname: '/storage/v1/object/public/**' },
    // Sanity-hosted section images (galleries, avatars, spotlights)
    { protocol: 'https', hostname: 'cdn.sanity.io' },
  ],
},

Raw Sanity asset refs (image-…) are never rendered — if the API sends one instead of a URL, the image is skipped and a warning names the fix. The desktop device-frame screenshot loads with priority (it's the usual desktop LCP element); everything else lazy-loads.

Quickstart

The fastest path — scaffold every route in one command from your Next.js project root (never overwrites existing files):

npx agency-site-kit-setup --site-url https://youragency.com

That writes the /work index, category filter routes, case study pages, loading/error surfaces, and the revalidate + preview API routes, then prints the finish-up checklist (env var, remotePatterns, sitemap, layout). Prefer wiring by hand? Everything it generates is described below.

1. Brand wrapper (app/layout.tsx)

import { AgencySiteKitLayout } from '@sonordev/agency-site-kit';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <AgencySiteKitLayout>{children}</AgencySiteKitLayout>
      </body>
    </html>
  );
}

Fetches the agency's brand config (colors, fonts) from Sonor and injects it as --sk-* CSS variables. Degrades to default branding if the API is unreachable — cosmetic fallback is the one place this package doesn't throw.

2. Case study pages (app/work/[slug]/page.tsx)

import { notFound } from 'next/navigation';
import { PortfolioPage, PortfolioSchema } from '@sonordev/agency-site-kit/portfolio';
import {
  getPortfolioItem,
  generatePortfolioMetadata,
  generatePortfolioStaticParams,
} from '@sonordev/agency-site-kit/portfolio/server';

export async function generateStaticParams() {
  return generatePortfolioStaticParams();
}

export async function generateMetadata({ params }) {
  const { slug } = await params;
  return generatePortfolioMetadata(slug);
}

export default async function CaseStudyPage({ params }) {
  const { slug } = await params;
  const item = await getPortfolioItem(slug);
  if (!item) notFound(); // null means the item genuinely doesn't exist

  return (
    <>
      <PortfolioSchema
        item={item}
        url={`https://youragency.com/work/${item.slug}`}
        publisher={{ name: 'Your Agency', url: 'https://youragency.com' }}
      />
      <PortfolioPage item={item} />
    </>
  );
}

3. The /work index (app/work/page.tsx)

PortfolioIndex is the turnkey, fully server-rendered index — grid, crawlable category links, pagination, and an intentional empty state, all with zero component JS:

import { PortfolioIndex } from '@sonordev/agency-site-kit/portfolio';
import { generatePortfolioIndexMetadata } from '@sonordev/agency-site-kit/portfolio/server';

export async function generateMetadata({ searchParams }) {
  const { page } = await searchParams;
  return generatePortfolioIndexMetadata({
    baseUrl: 'https://youragency.com',
    page: Number(page) || 1,
  });
}

export default async function WorkPage({ searchParams }) {
  const { page } = await searchParams;
  return (
    <PortfolioIndex
      page={Number(page) || 1}
      heading={<h1 className="text-4xl font-bold mb-8">Our Work</h1>}
    />
  );
}

Category filtering is route-based for SEO. In app/work/category/[category]/page.tsx:

import { PortfolioIndex } from '@sonordev/agency-site-kit/portfolio';
import { generatePortfolioCategoryStaticParams } from '@sonordev/agency-site-kit/portfolio/server';

export async function generateStaticParams() {
  return generatePortfolioCategoryStaticParams();
}

export default async function CategoryPage({ params, searchParams }) {
  const { category } = await params;
  const { page } = await searchParams;
  return <PortfolioIndex category={category} page={Number(page) || 1} />;
}

Loading and error surfaces (per route):

// app/work/loading.tsx
export { PortfolioIndexSkeleton as default } from '@sonordev/agency-site-kit/portfolio';

// app/work/[slug]/loading.tsx
export { PortfolioPageSkeleton as default } from '@sonordev/agency-site-kit/portfolio';

// app/work/error.tsx  (error boundaries must be client files)
'use client';
export { PortfolioErrorFallback as default } from '@sonordev/agency-site-kit/portfolio/client';

Prefer composing your own index? PortfolioGrid/PortfolioCard are shared components — server-render them directly, or import from @sonordev/agency-site-kit/portfolio/client inside client code. Fetch with getPortfolioItems() / getPortfolioCategories().

4. Sitemap entries (app/sitemap.js)

import { generatePortfolioSitemapEntries } from '@sonordev/agency-site-kit/portfolio/server';

const portfolio = await generatePortfolioSitemapEntries({
  baseUrl: 'https://youragency.com',
});
return [...staticEntries, ...portfolio];

5. Instant publish reflection (app/api/revalidate/route.ts)

import { createRevalidateHandler } from '@sonordev/agency-site-kit/revalidate';

export const { POST } = createRevalidateHandler();

Sonor calls this webhook when a case study is published/updated, busting the portfolio cache tag so changes appear near-instantly without a rebuild.

6. Draft preview (app/api/portfolio-preview/route.ts)

import { createPortfolioPreviewHandler } from '@sonordev/agency-site-kit/preview';

export const { GET } = createPortfolioPreviewHandler();

The dashboard's Preview button opens unpublished case studies on your live site through this route: it validates the short-lived token, enables Next draft mode, and getPortfolioItem fetches the draft uncached. Append ?exit=1 to leave preview mode. Tokens expire after an hour and only their hashes are stored.

Error contract

Content fetchers never conflate "not found" with "the API is down":

Not found — getPortfolioItem returns null (the API answered found: false). Map it to notFound().
Infrastructure failure (network error, 5xx, missing SONOR_API_KEY) — throws PortfolioApiError after 3 attempts with backoff. During ISR regeneration Next.js keeps serving the last good page; at build time the build fails loudly instead of silently shipping an empty portfolio, an empty sitemap, or fake 404s on indexed URLs.
getPortfolioBrandConfig is the deliberate exception: brand config is cosmetic, so it falls back to defaults rather than taking down the layout.

Subpath map

| Import | Side | What's there | |---|---|---| | @sonordev/agency-site-kit | server | Root barrel: layout, types, brand + API utils | | …/portfolio | server | PortfolioPage, PortfolioSchema, types | | …/portfolio/server | server | Data fetchers, metadata/static-params/sitemap helpers, PortfolioApiError, PORTFOLIO_CACHE_TAG | | …/portfolio/client | client | PortfolioGrid, PortfolioCard | | …/portfolio/sections/<Name> | per-file | Individual section components, à la carte | | …/portfolio/primitives/<Name> | client | Animation primitives (ScrollReveal, GlassCard, AnimatedCounter, …) for building custom sections | | …/layout | server | AgencySiteKitLayout | | …/revalidate | server | createRevalidateHandler |

Architecture: the RSC boundary

PortfolioPage is a server component. Each section decides its own side via the 'use client' directive in its source file — the build routes it to the matching bundle automatically:

Server sections (Challenges, Results, Services, Details, TechStack, Testimonial, SpeedComparison, DesignSystem) render on the server and ship zero component JS. They reach the animated primitives through …/portfolio/primitives/* subpaths — that import is the client boundary.
Client sections (Hero, Gallery, BeforeAfter, timelines, …) load through next/dynamic, so each becomes its own browser chunk fetched only when a case study actually uses that section type.

Two rules keep this safe (enforced by pnpm verify, which runs on publish):

Server code may only import client components via self-referencing package subpaths (@sonordev/agency-site-kit/portfolio/…), never relatively — a relative import would bundle client code into a server chunk and dissolve the boundary. That exact failure once serialized the entire PortfolioItemFull into the RSC flight payload on consumer sites.
A section that gains a hook or an event handler must also gain 'use client'. pnpm verify fails the publish if it doesn't.

Build landmines documented in tsup.config.ts: tsup's treeshake silently drops the 'use client' banner (rollup rewrite), and CJS + splitting destroys directive prologues (Sucrase). Don't re-enable either for the client builds.

Above-the-fold discipline: the hero's text column renders fully static — no entrance animation, no post-hydration re-hide — per the monorepo's Lighthouse doctrine (an element hidden after hydration can't be the LCP element).

Development

pnpm build       # three tsup passes: client ESM, client CJS, server
pnpm typecheck
pnpm verify      # RSC boundary checks against dist (also runs on publish)

prepublishOnly runs all three — a build that would leak the boundary can't be published.

Versioning

Pre-1.0 and currently consumed by a single site (upforge.io). The version stays at 0.4.0 while the hardening effort is in flight — nothing publishes until it's done. Breaking changes land in minor bumps with aggressive dead-code removal; that stance holds until a second agency adopts the package.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@sonordev/agency-site-kit

Install

Image optimization

Quickstart

1. Brand wrapper (app/layout.tsx)

2. Case study pages (app/work/[slug]/page.tsx)

3. The /work index (app/work/page.tsx)

4. Sitemap entries (app/sitemap.js)

5. Instant publish reflection (app/api/revalidate/route.ts)

6. Draft preview (app/api/portfolio-preview/route.ts)

Error contract

Subpath map

Architecture: the RSC boundary

Development

Versioning