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.
npm install ct-debug
# or
yarn add ct-debug
# or
pnpm add ct-debugCall initGtmDebugger() once in your application's root layout or entry component:
'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>
);
}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} />;
}import { initGtmDebugger } from 'ct-debug';
initGtmDebugger();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,
});
};- 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).
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
});Follow these step-by-step instructions to publish the ct-debug package to npm:
If you haven't logged in on your terminal yet:
npm login(Enter your npm username, password, and 2FA code)
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 buildVerify what files will be included in the published npm package:
npm pack --dry-runFor public publishing, run:
npm publish --access publicWhen 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 publicThe 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.
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:
Make your code changes, then stage and commit them:
git add .
git commit -m "feat: updated dataLayer debug feature"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 patch
-
New Feature Release (
1.0.0β1.1.0):npm version minor
-
Breaking Change Release (
1.0.0β2.0.0):npm version major
Push your commits and the new tag to GitHub:
git push origin main --tagsOnce 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.
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.
Distributed under the MIT License. Copyright Β© 2026 Mojahid.