CLI Installation
The TrackFox CLI is the fastest way to add analytics to your website. It automatically detects your framework, installs the tracking script in the correct location, and verifies the installation.
Quick Start
Install and run the CLI in one command:
npx trackfox add
That's it! The CLI will:
- Authenticate you with TrackFox
- Create or link your website
- Auto-detect your framework
- Install the tracking script
- Verify the installation
Installation
Option 1: Use with npx (Recommended)
No installation required - run directly:
npx trackfox add
Option 2: Install Globally
Install once, use anywhere:
npm install -g trackfox
trackfox add
Supported Frameworks
The TrackFox CLI supports automatic installation for 12 frameworks:
React Ecosystem
- Next.js - Both App Router and Pages Router
- React + Vite - Modern React applications
- Create React App (CRA) - Traditional React setup
- Remix - Full-stack React framework
- Gatsby - Static site generator
Vue Ecosystem
- Vue - Vite-based Vue projects
- Nuxt - The Vue framework
Svelte Ecosystem
- SvelteKit - The Svelte framework
- Svelte - Vite-based Svelte projects
Other Frameworks
- Astro - Content-focused framework
- Angular - Full-featured framework
- Static HTML - Plain HTML projects without a build system
How It Works
Step 1: Authentication
The CLI opens your browser for secure OAuth authentication:
$ npx trackfox add
š¦ TrackFox CLI - Add Website
Opening browser for authentication...
ā Authenticated!
Step 2: Website Configuration
Enter your website details:
? What is your website domain? example.com
? What would you like to name this website? My Awesome Site
ā Website created successfully!
Step 3: Automatic Installation
The CLI detects your framework and installs the script:
ā Setting up tracking script...
ā Detected: Next.js 14.0.0 (App Router)
ā Script installed successfully
ā Changes validated
Step 4: Completion
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā š Setup Complete! ā
ā ā
ā ā Website created ā
ā ā Tracking script installed ā
ā ā Framework: Next.js 14.0.0 (App Router)ā
ā ā
ā Modified files: ā
ā ā¢ app/layout.tsx ā
ā ā
ā Next steps: ā
ā 1. Review changes with git diff ā
ā 2. Test your site locally ā
ā 3. Deploy to production ā
ā 4. Check dashboard for analytics ā
ā ā
ā Dashboard: ā
ā https://trackfox.app/dashboard/abc123ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Remember to deploy these changes to start tracking!
Your Tracking Script
The CLI installs a script that looks like this:
<script
defer
src="https://trackfox.app/script.js"
data-website-id="your-website-id"
data-domain="example.com"
></script>
Attributes:
defer- Ensures the script doesn't block page loadingdata-website-id- Your unique website identifierdata-domain- Your website domain for tracking
Framework-Specific Details
Next.js
- App Router: Installs in
app/layout.tsxinside<head> - Pages Router: Installs in
pages/_document.tsxinside<Head>
React + Vite / Vue
- Installs in
index.htmlinside<head>
Remix
- Installs in
app/root.tsx
SvelteKit
- Installs in
src/app.htmlinside<head>
Nuxt
- Creates or updates
app.vueornuxt.config.ts
Astro
- Installs in layout files (e.g.,
src/layouts/Layout.astro)
Angular
- Installs in
src/index.htmlinside<head>
Gatsby
- Installs in
gatsby-ssr.jsusingsetHeadComponents
Static HTML
- Detects HTML files and guides manual installation
Commands
trackfox add
Add a new website and install the tracking script:
npx trackfox add
What it does:
- Authenticates with TrackFox
- Prompts for website domain and name
- Creates website in your dashboard
- Auto-detects your framework
- Installs tracking script
- Creates backup of modified files
- Validates the installation
Backup & Safety
The CLI automatically creates backups before modifying files:
- Backup location:
{filename}.trackfox.backup - Example:
app/layout.tsx.trackfox.backup
Verification
After installation, verify your setup:
- In your code: Check the modified file for the tracking script
- In your terminal: Review changes with
git diff - In your browser: Open DevTools Network tab and look for
trackfox.apprequests - In your dashboard: Use the "Verify Installation" button in Site Settings
Troubleshooting
Framework Not Detected
Problem: CLI can't detect your framework
Solution:
- Ensure
package.jsonexists in your project root - Check that framework dependencies are installed
- For static HTML, make sure
.htmlfiles exist - Follow manual installation instructions
Script Already Installed
Problem: CLI says script is already installed
Solution:
- The CLI detected an existing TrackFox script
- No changes needed - you're already set up!
- To reinstall, remove the existing script first
Permission Errors
Problem: EACCES or permission errors
Solution:
# Use npx instead of global install
npx trackfox add
# Or fix npm permissions
# https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
Next Steps
After installing TrackFox with the CLI:
- Review changes:
git diffto see what was modified - Test locally: Run your development server and check the Network tab
- Deploy: Push changes to production
- Monitor: Check your dashboard for analytics
- Custom events: Learn about event tracking
- Revenue tracking: Set up revenue analytics
FAQ
Does it work with monorepos?
Yes, run the CLI from the specific package directory where your website code lives.
Can I use it in CI/CD?
The CLI is designed for local development. For CI/CD, we recommend committing the tracking script to your repository.
What data does the CLI send?
The CLI only sends:
- Your authentication token (during OAuth)
- Website name and domain (during website creation)
- No source code or sensitive data is transmitted
Related Documentation
Need help? Contact us for assistance.
Suggest features? We'd love your feedback