+
+
+
-> A unified TypeScript library for tracking analytics across **Google Analytics 4**, **Meta (Facebook) Pixel**, and **TikTok Pixel**, built for React applications and beyond. +[](https://www.npmjs.com/package/@jadecubes/analytics) +[](https://www.npmjs.com/package/@jadecubes/analytics) +[](LICENSE) +[](https://www.typescriptlang.org/) +[](https://reactjs.org/) + +
+ ++ A unified TypeScript library for tracking analytics across Google Analytics 4, Meta (Facebook) Pixel, and TikTok Pixel +
+ ++ Built for React applications and beyond +
--- @@ -15,14 +29,14 @@ Modern front-ends often require multiple analytics platforms. Analytics offers: - **Lazy loading** of tracking scripts and automatic queueing of events. - Built with **TypeScript**, offering type definitions out of the box. - Designed for **React** (hooks + context) but easy to adapt. -- Built in an **Nx monorepo** for reuse across apps. +- Built with **Vite** for optimal bundle size and performance. --- ## 🧑💻 Who Should Use It? - Front-end engineers using React who want to track events across multiple analytics platforms. -- Teams managing **monorepos** (e.g., Nx, Turborepo) and looking for a shared analytics lib. +- Teams looking for a shared analytics library with a consistent API. - Developers who want a lightweight, configurable alternative to multiple SDKs. --- @@ -37,3 +51,124 @@ npm install @jadecubes/analytics # or with pnpm / yarn pnpm add @jadecubes/analytics +yarn add @jadecubes/analytics +``` + +--- + +## 📦 Publishing to npm + +This library is published as `@jadecubes/analytics` on npm. If you're a maintainer, follow these steps to publish a new version: + +### Prerequisites + +1. **npm Account**: Ensure you have an npm account and are logged in + ```bash + npm login + ``` + +2. **Organization Access**: You need publish access to the `@jadecubes` organization on npm + +### Publishing Steps + +1. **Update Version**: Update the version in `libs/analytics/package.json` following [semantic versioning](https://semver.org/): + - **Patch** (0.0.x): Bug fixes + - **Minor** (0.x.0): New features, backward compatible + - **Major** (x.0.0): Breaking changes + + ```bash + # Edit libs/analytics/package.json and update the version field + # For example: "version": "0.0.2" + ``` + +2. **Build the Library**: + ```bash + pnpm build + ``` + +3. **Test the Build**: Verify the build output in `dist/libs/analytics/` + ```bash + ls -la dist/libs/analytics/ + ``` + +4. **Copy package.json to dist**: The package.json needs to be in the dist directory + ```bash + cp libs/analytics/package.json dist/libs/analytics/ + ``` + +5. **Publish to npm**: + ```bash + cd dist/libs/analytics + npm publish --access public + ``` + +### Automated Publishing (Recommended) + +You can add a publish script to your root `package.json`: + +```json +{ + "scripts": { + "publish:analytics": "pnpm build && cp libs/analytics/package.json dist/libs/analytics/ && cd dist/libs/analytics && npm publish --access public" + } +} +``` + +Then simply run: +```bash +pnpm publish:analytics +``` + +### Publishing Beta/Alpha Versions + +For pre-release versions: + +```bash +# Update version to include tag, e.g., "0.1.0-beta.1" +cd dist/libs/analytics +npm publish --access public --tag beta +``` + +--- + +## 🛠️ Development + +### Project Structure + +``` +Analytics/ +├── libs/ +│ └── analytics/ # Main analytics library +│ ├── src/ +│ │ ├── core/ # Core analytics implementations +│ │ ├── react/ # React-specific providers +│ │ └── types/ # TypeScript types +│ └── vite.config.ts # Vite build configuration +├── docs/ # Documentation (Storybook) +└── tools/ # Build and development tools +``` + +### Available Scripts + +```bash +# Build the library +pnpm build + +# Run tests +pnpm test + +# Lint code +pnpm lint + +# Run Storybook for documentation +pnpm storybook + +# Build Storybook +pnpm build-storybook +``` + +--- + +## 📄 License + +MIT License - see [LICENSE](LICENSE) file for details diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 0c6c2c2..0000000 --- a/docs/README.md +++ /dev/null @@ -1,41 +0,0 @@ -# Website - -This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. - -### Installation - -``` -$ yarn -``` - -### Local Development - -``` -$ yarn start -``` - -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. - -### Build - -``` -$ yarn build -``` - -This command generates static content into the `build` directory and can be served using any static contents hosting service. - -### Deployment - -Using SSH: - -``` -$ USE_SSH=true yarn deploy -``` - -Not using SSH: - -``` -$ GIT_USER=