npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@smartive/utils

v4.4.0

Published

A set of general purpose utilities and helpers for web projects.

Readme

smartive Utilities

A collection of general purpose utilities and helpers for web projects.

Installation

npm install @smartive/utils

The root export (@smartive/utils) stays dependency-free. Optional peer dependencies are only required when you import the corresponding subpath.

Utilities

classNames

Cleans and joins an array of class names (strings and numbers), filtering out undefined and boolean values.

import { classNames } from '@smartive/utils';

const className = classNames('btn', isActive && 'btn-active', 42, undefined, 'btn-primary');
// Result: "btn btn-active 42 btn-primary"

getTelLink

Converts a phone number into a tel: link by removing non-digit characters (except + for international numbers).

import { getTelLink } from '@smartive/utils';

const link = getTelLink('+1 (555) 123-4567');
// Result: "tel:+15551234567"

@smartive/utils/http

Framework-agnostic HTTP helpers for token checks, open-redirect protection, and CORS headers.

import { isSafeRelativePath, isValidToken, withCORS } from '@smartive/utils/http';

isValidToken(request.headers.get('Webhook-Token'), process.env.CACHE_INVALIDATION_SECRET_TOKEN);
isSafeRelativePath('/relative/path');
withCORS({ status: 401 });

No environment variables are required by this subpath; callers pass secrets explicitly.

@smartive/utils/datocms

Typed GraphQL client factory wrapping @datocms/cda-client.

npm install @datocms/cda-client
import { createDatoClient, queryDatoCMS } from '@smartive/utils/datocms';

// Default client (reads env vars)
const data = await queryDatoCMS({ document: MyDocument, includeDrafts: true });

// Or configure explicitly
const query = createDatoClient({
  apiToken: process.env.DATOCMS_API_TOKEN,
  revalidate: 60 * 60,
});

| Env var | Purpose | | ------------------------------- | ------------------------------------------------- | | DATOCMS_API_TOKEN | Read-only CDA token (draft-capable when needed) | | DATOCMS_ENVIRONMENT | Optional X-Environment header | | NEXT_DATOCMS_BASE_EDITING_URL | Enables Content Link headers when querying drafts |

Config passed to createDatoClient always wins over environment variables.

On HTTP 429 a query waits for X-RateLimit-Reset (plus a few seconds of jitter) and retries up to maxRetries times (default 3) before rethrowing the cda-client ApiError. Set autoRetry: false to fail immediately. cda-client's own unbounded retry is always disabled.

@smartive/utils/datocms/next

The same client, backed by Next.js Cache Components instead of the fetch data cache. Queries are wrapped in use cache, tagged with a deterministic query ID, and given a cacheLife profile — so a DatoCMS publish can invalidate exactly the affected queries instead of purging the whole app.

Requires Next.js >= 16 with cacheComponents: true. Without that flag, use @smartive/utils/datocms.

npm install @datocms/cda-client @neondatabase/serverless
// lib/dato.ts
import { createNeonCacheTagStore } from '@smartive/utils/cache-tags/neon';
import { createCachedDatoClient } from '@smartive/utils/datocms/next';

export const store = createNeonCacheTagStore();

export const queryDatoCMS = createCachedDatoClient({ store });
// app/api/invalidate-cache-tags/route.ts
import { createCacheTagInvalidationHandler } from '@smartive/utils/next';
import { store } from '@/lib/dato';

export const { POST, GET, OPTIONS } = createCacheTagInvalidationHandler({ store });

Point a DatoCMS cache tags invalidation webhook at that POST route, with the secret in the Webhook-Token header.

There is deliberately no default client: one without a store looks like it works but can never be invalidated, so the store is a required, visible decision. Omitting it is still supported for local development — every entry then falls back to the short unstored lifetime.

cacheLife profiles

| Profile | Default | When it applies | | ---------- | ----------- | ------------------------------------------------------------------- | | cached | 'days' | The tag mapping persisted, so the webhook can reach the entry | | unstored | 'minutes' | The mapping could not be stored — the entry must expire on its own | | draft | 'seconds' | Draft mode is enabled (Next writes nothing to the cache regardless) |

Override per client via profiles, or per query via cacheProfile. A per-query override is ignored when the mapping did not persist, so it can never extend the lifetime of an entry the webhook cannot reach.

Draft mode

draftMode().isEnabled is read inside the cached scope, which Next.js permits. While draft mode is on, cached functions re-execute per request and nothing is written to the cache, so includeDrafts no longer needs threading through your data layer.

Pass includeDrafts: true (or skipCache: true) explicitly only when you need a guaranteed fresh read — preview slug resolution, for example. That bypasses the cached scope entirely.

@smartive/utils/cache-tags

The query-ID ⇄ DatoCMS cache-tag mapping used by @smartive/utils/datocms/next. Zero dependencies; no Next.js import.

import { buildQueryId, createMemoryCacheTagStore, parseXCacheTagsResponseHeader } from '@smartive/utils/cache-tags';

createMemoryCacheTagStore() is for tests, local development, and single-instance deployments only — on a serverless platform each instance would see a different subset of the mapping. It also accepts { configured: false } and { failing: true } for exercising fail-soft paths.

@smartive/utils/cache-tags/neon

import { cacheTagStoreSchemaSql, createNeonCacheTagStore } from '@smartive/utils/cache-tags/neon';

const store = createNeonCacheTagStore({ onError: (error) => captureException(error) });

Create the table once per Neon branch:

psql "$CACHETAGS_POSTGRES_URL" -c "$(node -e "import('@smartive/utils/cache-tags/neon').then((m) => console.log(m.cacheTagStoreSchemaSql()))")"

The store never throws: every method fails soft to a documented fallback and arms a 30-second backoff, because a store outage must degrade cache lifetimes rather than fail a page render. Writes report a boolean, and lookups return null on failure versus [] for "nothing matched" — that distinction is what drives the cacheLife choice and the webhook's 503-vs-200 response.

Isolate the store per DatoCMS environment (a Neon branch per deployment environment). The query ID already includes the resolved environment, but a table shared between apps also needs a tagPrefix.

| Env var | Purpose | | ------------------------ | -------------------------------------------- | | CACHETAGS_POSTGRES_URL | Neon connection string for the mapping table |

One synthetic tag per query, rather than one tag per DatoCMS record, is deliberate: Vercel caps a cache entry at 128 tags.

@smartive/utils/next

Next.js App Router helpers for draft mode, DatoCMS web previews, and cache revalidation.

npm install next
// app/api/draft/enable/route.ts
import { createDraftHandlers } from '@smartive/utils/next';

export const { enable: GET } = createDraftHandlers();

// app/api/draft/preview-links/route.ts
import { createWebPreviewsHandler } from '@smartive/utils/next';

export const { OPTIONS, POST } = createWebPreviewsHandler({
  baseUrl: 'https://example.com/api/draft',
  resolvePreviewUrl: async ({ item, itemType }) => {
    if (itemType.attributes.api_key === 'page') return `/${item.attributes.slug}`;
    return null;
  },
});

// app/api/revalidate-path/route.ts
import { createRevalidateHandler } from '@smartive/utils/next';

export const POST = createRevalidateHandler({ paths: ['/sitemap.xml'] });

Draft enable/disable and web-preview links use the url query parameter for redirect targets (e.g. /api/draft/enable?url=/page&token=…).

createRevalidateHandler revalidates '/' with 'layout' — the whole app — on every call. For per-query invalidation, use createCacheTagInvalidationHandler with a cache-tag store instead. createCacheTagInvalidateAllHandler covers the manual full reset (a missed webhook, or a change to the query-ID format).

| Env var | Purpose | | --------------------------------- | ------------------------------------------------------------------ | | DRAFT_SECRET_TOKEN | Authorizes draft enable/disable and web-previews | | CACHE_INVALIDATION_SECRET_TOKEN | Authorizes the revalidate and cache-tag webhooks (Webhook-Token) |

@smartive/utils/testing

Building blocks for sitemap-driven smoke tests. Zero dependencies, no browser.

import { checkUrls, fetchSitemapRoutes, formatUrlCheckFailures } from '@smartive/utils/testing';

const routes = await fetchSitemapRoutes({
  baseURL: 'http://localhost:3333',
  limits: [{ pattern: '/arbeiten/', max: 3 }], // sample large collections
  exclude: ['/ueber-uns/livebilder'],
});

const results = await checkUrls(routes, { baseURL: 'http://localhost:3333' });
  • fetchSitemapRoutes follows a sitemap index and includes xhtml:link alternates. It replaces the sitemap host with baseURL, deduplicates, applies exclude then limits, and throws when the sitemap is unreachable, slower than timeoutMs (default 30 s) or empty, so a broken sitemap never turns into a green run that checked nothing.
  • checkUrls requests every URL without following redirects (a redirecting sitemap URL fails), retries network errors and 5xx once, and never throws. formatUrlCheckFailures turns the failures into an assertion message.
  • parseSitemap, limitRoutes, excludeRoutes, toPath and isIgnored are exported for custom setups. Patterns are a string (substring) or a RegExp.

@smartive/utils/testing/playwright

Fixtures that fail a Playwright test on client-side errors: hydration mismatches, React errors, exceptions in client components, failed first-party requests. Only types are imported from @playwright/test, so install the version that matches your CI image:

npm install -D @playwright/test@<version of mcr.microsoft.com/playwright in your CI>

The automatic smoke fixture:

  • blocks every request that is not same-origin with baseURL or listed in allowHosts, so trackers, consent banners and embeds neither add noise nor send hits from CI
  • collects console errors and warnings (failOn), uncaught exceptions and unhandled rejections, first-party responses with status ≥ 400 and failed first-party requests
  • ignores console errors of blocked requests and expected aborts (<video> range requests, page close), drops entries matching ignore, and deduplicates
  • fails the test afterwards with the full list, attaches it as smoke-issues.json, and annotates the blocked hosts

Navigate with gotoAndSettle: waitUntil: 'load' plus a settle time (default 2 s) for hydration. Never networkidle, which a playing <video> prevents from ever arriving.

Recipe

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

const PORT = 3333; // not 3000, so reuseExistingServer never picks up `next dev`

export default defineConfig({
  testDir: 'test/smoke',
  globalSetup: './test/smoke/global-setup.ts',
  fullyParallel: true,
  workers: process.env.CI ? 2 : undefined,
  retries: process.env.CI ? 1 : 0,
  forbidOnly: !!process.env.CI,
  reporter: [['list'], ['junit', { outputFile: 'test-results/junit.xml' }], ['html', { open: 'never' }]],
  use: { baseURL: process.env.BASE_URL ?? `http://localhost:${PORT}`, trace: 'retain-on-failure' },
  projects: [{ name: 'chromium', use: devices['Desktop Chrome'] }],
  webServer: process.env.BASE_URL
    ? undefined
    : {
        command: `npm run build && npm run start -- -p ${PORT}`,
        url: `http://localhost:${PORT}/sitemap.xml`,
        timeout: 15 * 60_000,
        reuseExistingServer: !process.env.CI,
      },
});
// test/smoke/global-setup.ts
import { smokeGlobalSetup } from '@smartive/utils/testing/playwright';

export default smokeGlobalSetup({ limits: [{ pattern: '/arbeiten/', max: 3 }] });
// test/smoke/fixtures.ts
import { test as base } from '@playwright/test';
import { smokeFixtures, type SmokeFixtures } from '@smartive/utils/testing/playwright';

export const test = base.extend<SmokeFixtures>(
  smokeFixtures({
    allowHosts: ['*.datocms-assets.com', 'stream.mux.com', 'image.mux.com'],
    ignore: ['Please ensure that the container has a non-static position'],
  }),
);
export { expect } from '@playwright/test';
// test/smoke/pages.spec.ts
import { gotoAndSettle, readRoutes } from '@smartive/utils/testing/playwright';

import { expect, test } from './fixtures';

for (const route of readRoutes()) {
  test(route, async ({ page }) => {
    const response = await gotoAndSettle(page, route);

    expect(response?.status()).toBe(200);
  });
}
// test/smoke/http.spec.ts – plain `test`, so no browser is started
import { expect, test } from '@playwright/test';
import { checkUrls, fetchSitemapRoutes, formatUrlCheckFailures } from '@smartive/utils/testing';

test('every sitemap URL returns 200', async ({ baseURL }) => {
  const results = await checkUrls(await fetchSitemapRoutes({ baseURL: baseURL! }), { baseURL });

  expect(formatUrlCheckFailures(results)).toBe('');
});
# .gitlab-ci.yml
tests:
  image: mcr.microsoft.com/playwright:v<same version as @playwright/test>-noble
  script:
    - npm ci
    - npx playwright test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  artifacts:
    when: always
    expire_in: 1 week
    reports:
      junit: test-results/junit.xml
    paths: [playwright-report/, test-results/]

Notes

  • Why global setup: Playwright runs webServer and globalSetup before it loads test files, so the spec can generate one test per route from the file smokeGlobalSetup writes (default node_modules/.cache/smartive-utils/smoke-routes.json). Every worker reads the same list, even if the sitemap changes mid-run. Setup projects run too late for this. playwright test --list skips global setup and lists no routes.
  • Existing Playwright setup: globalSetup applies to a whole config, so put the smoke suite in its own playwright.smoke.config.ts and run it with playwright test -c playwright.smoke.config.ts.
  • Per-file options: test.use({ smokeOptions: { failOn: ['error'] } }). They are merged over the options passed to smokeFixtures: ignore and allowHosts add to them, the other fields replace them.
  • Expecting issues: a test can assert on smoke.issues and empty it (smoke.issues.length = 0) to pass.
  • CommonJS projects (most Next.js apps) work: Playwright compiles the specs to require(), and both subpaths have a default export condition for that.
  • Keep the version in sync: group @playwright/test and mcr.microsoft.com/playwright in one Renovate rule, otherwise the browser in the image and the runner drift apart.
  • Retries rerun every failure, so an intermittent console error shows up as flaky and passes. Set failOnFlakyTests: true to fail on it instead.
  • Video is never really played: Playwright's Chromium has no H.264 decoder. Only the page around it is checked.

Migrating from @smartive/datocms-utils

This package was previously published as @smartive/datocms-utils. With 4.0.0 it was renamed to @smartive/utils and the old cache-tag utilities were removed.

  • classNames and getTelLink are unchanged — only the import specifier needs to be updated.
  • DatoCMS / Next.js helpers live under @smartive/utils/http, @smartive/utils/datocms, and @smartive/utils/next.

Cache tags

The cache-tag utilities are back, rebuilt for Next.js Cache Components. You no longer need to stay on @smartive/datocms-utils@3.

| Removed in 4.0.0 | Replacement | | ------------------------------- | ------------------------------------------------------- | | CacheTagsProvider (interface) | CacheTagStore from @smartive/utils/cache-tags | | NeonCacheTagsProvider | createNeonCacheTagStore (/cache-tags/neon) | | NoopCacheTagsProvider | createMemoryCacheTagStore (/cache-tags) | | RedisCacheTagsProvider | Not ported — open an issue if you need it | | generateQueryId | buildQueryId — different output format, see below | | parseXCacheTagsResponseHeader | Unchanged, now from @smartive/utils/cache-tags | | CacheTag (branded type) | Plain string | | CacheTagsInvalidateWebhook | Unchanged, plus an isCacheTagsInvalidateWebhook guard |

Behavioural changes worth knowing:

  • Query IDs changed format. buildQueryId emits <operationName>-<hash16> rather than a bare sha1, so every stored mapping from v3 is unreachable. Run the invalidate-all handler once after upgrading to clear them.
  • Stores never throw. The throwOnError option is gone: a store outage must degrade cache lifetimes, not fail a render. onError remains, for telemetry.
  • Return types carry more signal. storeQueryCacheTags returns boolean and queriesReferencingCacheTags returns string[] | null, which is what lets the client pick a cacheLife profile and the webhook distinguish 503 from 200.
  • buildQueryId needs no graphql dependency. It hashes the document structurally, ignoring loc, so graphql-tag output is stable across unrelated edits in the same file.

License

MIT © smartive AG