ct-debug
v1.0.1
Published
Headless Google Tag Manager (GTM) dataLayer wrapper and debug overlay for web applications
Maintainers
mojahid2021Readme
ct-debug
A headless, zero-dependency Google Tag Manager (GTM) dataLayer wrapper and real-time debug overlay for web applications, Next.js, React, and single-page applications.
Decouple analytics instrumentation from your application logic while retaining full visibility into your dataLayer events without needing to launch GTM preview mode.
📥 Installation
npm install ct-debug
# or
yarn add ct-debug
# or
pnpm add ct-debug🚀 How to Implement in Your App
1. Zero-Configuration Initialization
Call initGtmDebugger() once in your application's root layout or entry component:
Next.js (App Router: app/layout.tsx):
'use client';
import { useEffect } from 'react';
import { initGtmDebugger } from 'ct-debug';
export default function RootLayout({ children }: { children: React.ReactNode }) {
useEffect(() => {
// ⚡ Zero-config: Automatically enables UI & Console logs in Development environment
initGtmDebugger();
}, []);
return (
<html lang="en">
<body>{children}</body>
</html>
);
}Next.js (Pages Router: pages/_app.tsx):
import { useEffect } from 'react';
import { initGtmDebugger } from 'ct-debug';
import type { AppProps } from 'next/app';
export default function MyApp({ Component, pageProps }: AppProps) {
useEffect(() => {
initGtmDebugger();
}, []);
return <Component {...pageProps} />;
}Vanilla JS / Vite:
import { initGtmDebugger } from 'ct-debug';
initGtmDebugger();2. Pushing DataLayer Events
Import pushToDataLayer anywhere in your application (UI components, button handlers, form submissions):
import { pushToDataLayer } from 'ct-debug';
// Example: Button Click
const handleButtonClick = () => {
pushToDataLayer('button_click', {
button_name: 'hero_cta',
category: 'engagement',
});
};
// Example: User Signup Event
const handleUserSignup = (user) => {
pushToDataLayer('sign_up', {
method: 'email',
user_id: user.id,
});
};⚡ Smart Environment Detection & URL Toggling
- Development (
NODE_ENV === 'development'): Debugger UI overlay and browser console logs are enabled automatically. - Production (
NODE_ENV === 'production'): Debugger UI overlay is disabled automatically so end-users never see it. - URL Override: Want to open the overlay on Staging or Production? Add
?gtm_debug=trueto any URL in your browser (e.g.https://yoursite.com/page?gtm_debug=true).
⚙️ Optional Configuration Options
initGtmDebugger(options) accepts optional parameters if you need custom behavior:
initGtmDebugger({
gtmId: 'GTM-XXXXXXX', // Optional: automatically injects GTM script into <head>
enableUi: true, // Optional: force enable UI overlay
debug: true, // Optional: force enable console logging
});📦 How to Publish ct-debug to npmjs.com
Follow these step-by-step instructions to publish the ct-debug package to npm:
Step 1: Login to your npm Account
If you haven't logged in on your terminal yet:
npm login(Enter your npm username, password, and 2FA code)
Step 2: Verify Package Build
Run the build script to ensure all ESM (dist/index.mjs), CJS (dist/index.js), and TypeScript definitions (dist/index.d.ts) are generated cleanly:
npm run buildStep 3: Test Package Contents
Verify what files will be included in the published npm package:
npm pack --dry-runStep 4: Publish to npm
For public publishing, run:
npm publish --access publicStep 5: Updating / Publishing New Versions
When you make updates in the future, bump the version before re-publishing:
# For bug fixes (1.0.0 -> 1.0.1)
npm version patch
# For new features (1.0.0 -> 1.1.0)
npm version minor
# For breaking changes (1.0.0 -> 2.0.0)
npm version major
# Then publish the new version
npm publish --access public� How to Version, Push & Publish Automatically
The repository is configured with GitHub Actions (.github/workflows/publish.yml). Whenever you push a version tag (e.g. v1.0.1), GitHub Actions automatically:
- Builds & type-checks your code.
- Publishes the package to npmjs.com.
- Creates a GitHub Release with auto-generated release notes and attached
.tgzpackage.
Step-by-Step Release Guide
1. One-Time Setup: Add npm Token to GitHub Secrets
If you haven't added your npm token to GitHub yet:
- Log in to npmjs.com > Access Tokens > Generate New Token (Automation or Granular with Read/Write for
ct-debug). - Go to GitHub repo mojahid2021/ct-debug > Settings > Secrets and variables > Actions.
- Click New repository secret:
- Name:
NPM_TOKEN - Secret: (Paste your npm token)
- Name:
2. Make Code Changes & Commit
Make your code changes, then stage and commit them:
git add .
git commit -m "feat: updated dataLayer debug feature"3. Bump Version (Creates Git Tag)
Use npm version to bump your package version. This automatically updates package.json and creates a corresponding git tag (e.g. v1.0.1):
Bug Fixes / Patch Release (
1.0.0➔1.0.1):npm version patchNew Feature Release (
1.0.0➔1.1.0):npm version minorBreaking Change Release (
1.0.0➔2.0.0):npm version major
4. Push Commits & Tags to GitHub
Push your commits and the new tag to GitHub:
git push origin main --tags⚡ What Happens Next Automatically:
Once pushed, GitHub Actions triggers the Publish Pipeline:
- 📦 npmjs.com:
ct-debugis compiled and published directly to npm. - 🚀 GitHub Releases: A new Release entry is published on
https://github.com/mojahid2021/ct-debug/releasescontaining release notes and the build artifact.
🤝 Contributing
Contributions are welcome! Please see our Contributing Guide and Code of Conduct for details on how to set up the repository and submit pull requests.
📄 License
Distributed under the MIT License. Copyright © 2026 Mojahid.