@hifilabs/create-pixel
v0.1.8
Published
Set up artistPixel analytics in your Next.js project in under 30 seconds
Readme
@hifilabs/create-pixel
Set up artistPixel analytics in your Next.js project in under 30 seconds.
One command installs the SDK, configures your environment variables, and generates a ready-to-use provider component — for both the App Router and the Pages Router.
npx @hifilabs/create-pixelScope: v1 supports Next.js (App Router + Pages Router).
Quick Start
# Interactive (recommended)
npx @hifilabs/create-pixel
# Non-interactive (CI/scripting)
npx @hifilabs/create-pixel --artist-id ART123 --project-id custom_mysite --yesYou'll need your Artist ID and a Project ID from your artistHQ dashboard.
CLI Options
| Flag | Description |
|------|-------------|
| --artist-id <id> | Artist ID from your artistHQ dashboard |
| --project-id <id> | Project ID for this website (e.g. custom_main_website) |
| --yes, -y | Skip all prompts (needs --artist-id or an existing .env.local) |
| --help, -h | Show help message |
What It Does
- Pre-flight — verifies you're in a Next.js project, checks for an existing install and
.env.localconfig - Framework detection — App Router (
app/) vs Pages Router (pages/), package manager (pnpm/yarn/bun/npm), TypeScript vs JavaScript - Artist configuration — prompts for (and validates) your Artist ID and Project ID
- Third-party pixels (optional) — Google Tag Manager, Meta Pixel, TikTok Pixel, Google Ads conversion tracking
- Consent mode — choose how visitor consent is managed (see below)
- Execute — installs
@hifilabs/pixel, writes/merges.env.local, copies the browser script topublic/scripts/, and generates your provider component
Consent modes
| Mode | Description |
|------|-------------|
| Built-in (default) | artistPixel's built-in consent banner |
| Built-in, no banner | No consent UI — the pixel runs privacy-first session tracking until your site grants consent via setConsent() |
| c15t | Full GDPR/CCPA compliance via c15t.com — installs @c15t/react (required; the generated provider imports and injects it) |
| External | Bring your own consent manager (OneTrust, Cookiebot, etc.) |
| Disabled | No consent management |
Generated Files
.env.local
# artistPIXEL Configuration
NEXT_PUBLIC_ARTIST_ID=your_artist_id
NEXT_PUBLIC_PROJECT_ID=custom_your_project
NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX # if provided
NEXT_PUBLIC_META_PIXEL_ID=1234567890 # if provided
NEXT_PUBLIC_TIKTOK_PIXEL_ID=ABC123 # if provided
NEXT_PUBLIC_GOOGLE_ADS_ID=AW-123456789 # if provided
NEXT_PUBLIC_GOOGLE_ADS_CONVERSION_LABEL=AbCdEf123 # if Google Ads ID providedEnvironment variables are merged, never overwritten — existing values are preserved.
Provider component
For the App Router, app/providers/pixel-provider.tsx:
'use client';
import React from 'react';
import { ArtistOS } from '@hifilabs/pixel';
export function PixelProvider({ children }: { children: React.ReactNode }) {
return (
<ArtistOS debug={process.env.NODE_ENV === 'development'}>
{children}
</ArtistOS>
);
}Then wrap your app in app/layout.tsx:
import { PixelProvider } from './providers/pixel-provider';
// Inside <body>:
<PixelProvider>{children}</PixelProvider>For the Pages Router, the CLI generates components/PixelProvider.tsx (no 'use client' directive) — wrap <Component /> in pages/_app.tsx the same way.
The ArtistOS component reads all IDs from the environment variables automatically — no props needed.
Re-run Safety
The CLI is idempotent — safe to run again at any time:
| Scenario | Behavior |
|----------|----------|
| @hifilabs/pixel already installed | Skips install |
| .env.local already has NEXT_PUBLIC_ARTIST_ID | Shows the value, asks "update or keep?" |
| Provider file exists | Asks "overwrite or skip?" (with --yes: always skips) |
| Monorepo root detected | Warns, suggests running in the app directory |
Capturing Signups
The scaffold wires up the provider and consent; call identify() from your own forms to capture fan signups:
import { useArtistPixelIdentify } from '@hifilabs/pixel';
const { identify } = useArtistPixelIdentify();
function onSubmit(email: string, phone?: string, smsChecked?: boolean) {
identify(email, {
...(phone ? { phone, smsOptIn: !!smsChecked } : {}),
emailOptIn: true, // forwards to the artist's connected email tool, if configured
consentVersion: 'signup-v1',
});
}An explicit opt-in captures the signup even if the visitor declined the analytics banner.
License
MIT © HiFi Labs