Planet Clicket

Planet Clicket – A Practical Walkthrough

I ran into this thing while trying to parse some raw clickstream logs for a client project. The documentation is thin, so I ended up figuring most of it out by trial and error. Here is what I learned. Planet Clicket is a lightweight event-tracking library that captures user interactions and ships them to a collector endpoint. It is written in TypeScript, targets modern browsers, and intentionally avoids the bloat of enterprise analytics suites. You drop it into a project, configure the tracking domain, and you are collecting events within minutes. I use it for internal product telemetry where I do not want to hand off user data to a third-party SaaS. Run this in your project root:

npm install planet-clicket --save Or if you prefer yarn: yarn add planet-clicket

It also works with pnpm. The package is small enough that bundle size is not a concern. I measured about 4.2 kilobytes minified and gzipped, which is reasonable for a tracking library.

Basic Setup

Here is the minimal configuration that gets you firing events: The deviceId: 'auto' setting generates a persistent UUID stored in localStorage. It survives page reloads and new sessions. That matters because without it, every page refresh looks like a different user. I learned that the hard way on my first project. The first problem I hit was duplicate events firing when components re-rendered rapidly in React. The library does not debounce by default. I solved it by wrapping my track calls in a simple throttler:

That cuts duplication without noticeably delaying the data. Two hundred milliseconds is plenty of headroom for user interactions. Another issue: the default endpoint requires a specific request format. If you send a plain JSON body, you get a 400 back. The collector expects a payload with a top-level events array, each event carrying timestamp, type, and properties. Use the built-in serializer:

const batch = clicket.serializeBatch()
fetch('https://telemetry.yourdomain.com/events', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(batch),
})

Advanced: Custom Properties

You can attach arbitrary key-value pairs to any event. Just pass them as the second argument. Keep values serializable. Strings, numbers, and booleans work. Arrays and objects sometimes trip up older collectors that do not handle nested structures. I discovered this when a client's pipeline choked on an object property containing form field metadata. I flattened it manually and the problem disappeared. Also worth noting: the library batches events automatically every 30 seconds or when you hit 10 events, whichever comes first. During development I turned on debug: true and saw the batch flush happening exactly at those thresholds. Good to know if you are debugging missing events.

When Not to Use It

Planet Clicket is not built for GDPR-compliant consent flows out of the box. There is no built-in cookie banner integration or opt-out mechanism. If your project requires that, you will need to wrap the track calls in your own consent check. It adds a line of code, but it is easy to miss during a rush. I once shipped a beta where every click was being logged before the user accepted the privacy notice. Had to hotfix that. It also does not support server-side rendering. If you try to import it in a Node environment without a polyfill for window and localStorage, it crashes. I worked around that by lazy-loading the module after mount in Next.js:

useEffect(() => {
  import('planet-clicket').then(({ Clicket, configure }) => {
    configure({ endpoint: '...', deviceId: 'auto' })
    // now safe to track
  })
}, [])

That keeps SSR from breaking. The package lives on npm under the name planet-clicket. GitHub repository is public. Source code is available, which helped me understand the batch serializer when I needed to extend it for a custom property format. The maintainer responds to issues within a day or two, which is better than I see from most open-source telemetry tools. If you want something lighter, there are smaller alternatives. But Planet Clicket hits a sweet spot for teams that want full control over their event pipeline without importing a massive analytics SDK.