Announcing Crayons v3 — new components with breaking changes

We have released a new major version of Crayons, with support for more than 18 new components, and a set of new features:

  1. Existing components from v2 now support additional customisation by modifying props
  2. Framework bindings for React — allowing React apps to listen and react to events emitted by Crayons components
  3. Framework support and usage examples for Vue and Angular
  4. Internationalization (i18n) support — allowing you to build multi-lingual interfaces with Crayons
  5. New CSS utilties for typography, spacing, border, layout, card and color.
  6. Ability to add external icons
  7. Accessibility (a11y) support for all components
  8. Style customization using CSS variables
  9. Tree-shakeable bundle for components — allowing reduction in bundle sizes

Breaking changes for Crayons v2 users

Important changes to CDN URLs for Crayons

Important: The default CDN URL serving Crayons now serves v3. As a result, existing apps using Crayons v2 must either migrate to v3, or change the CDN URL of Crayons to continue on v2.

To stay on v2, change the CDN URL to the following (notice the @2 in the URL):

<script
  type="module"
  src="https://unpkg.com/@freshworks/crayons@2/dist/crayons/crayons.esm.js">
</script>
<script
  nomodule
  src="https://unpkg.com/@freshworks/crayons@2/dist/crayons/crayons.js">
</script>

Warning: If you intend to stay on v2, then publishing a new version of an app without changing the CDN URL to point to @2 will break your app!

Update (April 6, 2022): The default URL, the one without a version tag, now points to Crayons v2. So, apps that use Crayons v2 today with the default URL will receive Crayons v2, and not break. For v3, use the @v3 URL as mentioned in the Crayons installation documentation.

Other breaking changes

Please see the list of all breaking changes from Crayons v2 to v3.

Migrating to v3

Please follow the guide on Migrating to v3.

8 Likes

Awesome update guys. Looks excellent. Love the new components.

2 Likes

Wow, can’t wait to test it!

Just to confirm: if I don’t upload a new version of an app using the default CDN url, it won’t break, right?

1 Like

It can break, unfortunately, since the CDN content has changed. So, all apps using the default URL will now get v3. :frowning_face:

That said, we had identified existing apps that use Crayons v2 and made a patch to all those apps to point them to the @2 URL for now. Please check and confirm if your app is breaking.

1 Like

I don’t believe this was the best approach. I have delivered a lot of custom apps to customers using crayons that I can’t even remember. Imagine if all of them start reaching out me with trouble…
I don’t recall the v2 docs from before this new release saying anything about version on the getting started section, there was just one link.
I would appreciate if you guys could review this approach.

5 Likes

I do agree with you @samuelpares. We will have to do a better job at retaining backwards compatibility.

Any suggestions on what approach would have helped you better? Would namespacing the new version with a @3 url and/or making upgrades optional help?

3 Likes

Yes! I believe that leaving the cdn from before, pointing to v2, and starting versioning now from v3 would solve the problem.

2 Likes

Understood Thanks again @samuelpares. I shall take your feedback back to the Crayons team. Meanwhile, if anything breaks, please do let us know.

2 Likes

FYI customers already begun contacting me with trouble.
For now I’m changing the app to v2.
So updating the suggestion above:

  • Make the default url point to v2
  • Make the @v2 point to v2
  • @v3 point to v3
2 Likes

Thanks for the update @samuelpares. My sincere apologies on behalf of the team for the botched DX here.

Pointing the default URL to v2 may not be possible right away from the same package because unpkg automatically serves the latest published version of the npm package in the default URL. We also don’t want to fork the package.

We plan to get our teams together to see how we can address this, very soon. I’ll keep you posted.

I’m curious to know if all of these apps are Freshworks apps, or do you use Crayons in non-Freshworks apps as well.

2 Likes

It’s all freshworks custom apps!

2 Likes

3 posts were split to a new topic: App is stuck in Draft state since Crayons release

I just did some testing and it seems so :frowning:

We have changed the Crayons CDN URLs to serve v2 from the default URL. So, existing apps on v2 should no longer break. @msenhaji this should fix your issue. If not, please let me know.

@samuelpares Thank you again for suggesting the changes. The current setup is as you had suggested:

  • The default URL now points to version 2.x
  • The URL with @2 or @v2 now points to version 2.x
  • The URL with @3 or @v3 now points to version 3.x

Once again, on behalf of the team, our sincere apologies for breaking your apps. :pray:

5 Likes

This topic was automatically closed after 60 days. New replies are no longer allowed.