Analytics next - Upgrade guide

v5 to v6

✨ TypeScript support

Analytics-next is now completely written in TypeScript

🧠 HOC Type inference

In v5, the main problem areas for analytics-next, with regards to TypeScript, was withAnalyticsEvents and withAnalyticsContext. These two HOCs never quite worked as expected, often relying on consumers to cast the return value of the function back into the component they wish to export. Recently this was partially mitigated by accepting prop types as generics, returning TS type safety with one downside, props must be passed into every usage of our HOCs.

Now in v6, support for type inference is built-in so you no longer have to explicitly pass props as generic types.

📝 Renaming types and interfaces

analytics-next previously provided typings via a module declaration file (index.d.ts), which was actually slightly misaligned with the source code. Some interfaces were used to describe classes, and some classes of the same name were also being exported to avoid name clashes. v6 removes those discrepancies by renaming and removing misaligned type definitions. See breaking changes for more information.

💥 Breaking Changes:

  • flow types have been removed
  • withAnalyticsEvents now infers proptypes automatically, consumers no longer need to provide props as a generic type.
  • withAnalyticsContext now infers proptypes automatically, consumers no longer need to provide props as a generic type.
  • Type WithAnalyticsEventProps has been renamed to WithAnalyticsEventsProps to match source code
  • Type CreateUIAnalyticsEventSignature has been renamed to CreateUIAnalyticsEvent to match source code
  • Type UIAnalyticsEventHandlerSignature has been renamed to UIAnalyticsEventHandler to match source code
  • Type AnalyticsEventsPayload has been renamed to AnalyticsEventPayload
  • Type ObjectType has been removed, please use Record<string, any> or [key: string]: any
  • Type UIAnalyticsEventInterface has been removed, please use UIAnalyticsEvent
  • Type AnalyticsEventInterface has been removed, please use AnalyticsEvent
  • Type CreateAndFireEventFunction removed and should now be inferred by TypeScript
  • Type AnalyticsEventUpdater removed and should now be inferred by TypeScript

⬆️ Upgrade guide

Applicable to TypeScript users only

Renaming types and interfaces

Most of the breaking changes above can be avoided with a 'find-and-replace' of the following types/interfaces:

  • WithAnalyticsEventProps => WithAnalyticsEventsProps
  • CreateUIAnalyticsEventSignature => CreateUIAnalyticsEvent
  • UIAnalyticsEventHandlerSignature => UIAnalyticsEventHandler
  • AnalyticsEventsPayload => AnalyticsEventPayload

Some interfaces were used to describe a class instance. This is no longer needed since a class in TypeScript can be used as a type. These interfaces should be replaced by their class equivalents:

  • UIAnalyticsEventInterface => UIAnalyticsEvent
  • AnalyticsEventInterface => AnalyticsEvent

The following types have been removed from the library and can either be safely replaced with an alternate type or removed entirely in favour of type inference:

  • ObjectType => Record<string, any> or [key: string]: any
  • CreateAndFireEventFunction now inferred by TypeScript
  • AnalyticsEventUpdater now inferred by TypeScript

Using withAnalyticsEvents and withAnalyticsContext with type-safety

After upgrading to v6, you might now be greeted with TypeScript errors relating to withAnalyticsEvents and withAnalyticsContext. As described above, there have been a lot of changes to the way types are applied to these HOCs.

Previously, props needed to be explicitly defined and passed in as generic type arguments. Now, you should be able to remove the generic types and let TypeScript do the heavy lifting.

For example:

Before…

withAnalyticsContext<ButtonProps>({})(Button); withAnalyticsEvents<ButtonProps>({})(Button);

After…

withAnalyticsContext({})(Button); withAnalyticsEvents({})(Button);

This does however require you to extend your component's props with WithAnalyticsEventProps. A common pattern you’ll find with other HOC implementations, used to ensure you’re passing the correct super type to the HOC.

import { WithAnalyticsEventsProps } from '@atlaskit/analytics-next'; interface ButtonProps extends WithAnalyticsEventsProps { appearance: string, }

To provide additional flexibility, you can now opt-out of type inference if needed. It might be necessary in edge-cases where TypeScript is not able to infer the prop types of the component you have supplied. If that's the case, try passing in the generic type arguments to withAnalyticsEvents.

export default withAnalyticsContext({})( withAnalyticsEvents({}) < ButtonProps, React.ComponentType<ButtonProps> >(Button), );