Step 1
Install the SDK package
Add faurya to your project dependencies with npm install faurya.
NPM SDK Integration
Install Faurya and Start Tracking in Minutes
Use the official Faurya npm package, run the init flow once, and ship web or React Native analytics with generated helpers and runtime controls.
Start your free trial • Publishes in 1-click • Cancel anytime
★★★★★
Trusted by 5,000+ founders, marketers and agencies
NPM SDK setup screen with install/init flow, generated config files, and environment setup guidance.
Start Here (Recommended)
Install once, run init once, then add env values and restart your dev server.
Step 2
Run the setup command
Execute npx faurya init to scaffold integration files and safe config updates.
Step 3
Set required environment values
Add FAURYA_SITE_ID and FAURYA_DOMAIN, and FAURYA_API_KEY when using server helpers.
Step 4
Restart and verify tracking
Restart your app and confirm events are appearing in your Faurya dashboard.
Setup commands
npm install faurya
npx faurya initRequired env values
FAURYA_SITE_ID=your-site-id
FAURYA_DOMAIN=your-domain.comIf you choose server API helpers, also add FAURYA_API_KEY to server-side env.
What npx faurya init Adds
The CLI scaffolds safe defaults, config updates, and integration files so setup is fast and consistent.
- Detects your framework (Next.js App Router, Next.js Pages Router, Vite React, or safe fallback)
- Creates or updates environment keys without overwriting existing values
- Generates browser init helper files for client tracking
- Injects initialization into app entry points when safe
- Prints setup summary and next steps for your project
- Optionally scaffolds server API helpers for goals and payments
Generated Helpers
When you choose API helper scaffolding, these are the primary calls developers use in app code.
createFauryaGoal
createFauryaGoal(fauryaVisitorId, name, metadata?)
Server helper to track goal conversions with optional metadata fields.
import { createFauryaGoal } from "./lib/faurya-api";
await createFauryaGoal("visitor_123", "signup", {
source: "pricing_page",
campaign: "spring_launch",
});createFauryaPayment
createFauryaPayment(amount, currency, transactionId, options?)
Server helper for payment tracking with customer, renewal, refund, and timestamp options.
import { createFauryaPayment } from "./lib/faurya-api";
await createFauryaPayment(99, "USD", "txn_002", {
customerId: "cus_789",
renewal: false,
refunded: false,
});trackFauryaEvent
trackFauryaEvent(eventName, metadata?)
Client helper generated in lib/faurya.ts for custom events in app code.
import { trackFauryaEvent } from "./lib/faurya";
trackFauryaEvent("initiate_checkout", {
product_id: "prod_123",
plan_type: "pro",
currency: "USD",
});initFaurya Runtime Configuration
Use direct SDK initialization when you need full control over privacy, queueing, pageview behavior, and runtime guards.
| Option | Meaning |
|---|---|
| websiteId | Required project/site identifier in Faurya. |
| domain | Strongly recommended to pass explicitly so routing stays consistent. |
| apiUrl | Optional API base URL override for custom endpoints. |
| cookieless | Disables cookie-based identity flow. |
| autoCapturePageviews | Controls initial pageview capture, hash tracking, and debounce timing. |
| allowLocalhost / allowIframe | Runtime guards for localhost and iframe execution contexts. |
| flushInterval / maxQueueSize | Controls queue flush timing and batch behavior. |
| enableAttentionTracking / enablePageviewEnd | Enables attention and page-exit summary events. |
| autoDetectPayments / enableGoalTracking | Enables payment auto-detection and data-faurya-goal capture. |
CLI Options and Env Behavior
These are the practical defaults and guardrails used during setup.
| Item | Current behavior |
|---|---|
| Command | npx faurya init |
| CLI options | --with-api (or --api), --no-api, or interactive prompt |
| Always-used env keys | FAURYA_SITE_ID, FAURYA_DOMAIN |
| Server helper env key | FAURYA_API_KEY (only when API helpers are enabled) |
| Env file update target | Next.js uses .env.local, Vite/Unknown uses .env |
| Existing values | Non-empty values are preserved and never overwritten |
| Next config exposure | Adds env mappings for FAURYA_SITE_ID and FAURYA_DOMAIN when patching is safe |
| Vite exposure | Adds envPrefix: ['VITE_', 'FAURYA_'] when patching is safe |
Troubleshooting
Common setup messages and what to do next.
+Missing FAURYA_SITE_ID
Add FAURYA_SITE_ID to your env file, restart your dev server, and re-open your app.
+Missing FAURYA_API_KEY
Add FAURYA_API_KEY to server environment only when you use server API helpers.
+Could not safely update Next or Vite config
Patch config manually with env mappings (Next) or envPrefix update (Vite), then rerun if needed.
+Layout or app injection point not found
Add FauryaAnalytics manually in your app entry if the CLI cannot find body or Component injection points.
+Unknown command
Use npx faurya init for setup. Other unsupported commands return an unknown command message.
FAQ
What is the fastest setup path?
Install the package and run npx faurya init once. Then set FAURYA_SITE_ID and FAURYA_DOMAIN.
Is this only for web apps?
The package supports web and React Native, with subpath exports for each surface.
Can I skip generated helpers and use direct SDK calls?
Yes. You can call initFaurya directly and use track, trackGoal, trackPageview, identify, flush, and reset.
Does init overwrite existing env values?
No. Existing non-empty values are preserved. Missing keys are appended.
Where can I install the package?
Use the official npm package page linked in the hero section and command snippets.