Skip to main content

Best Practices

Packages and Dependencies​

Because Cloudflare Workers don’t run in traditional containerized environments with full Node.js runtimes, certain Node-specific modules—such as fs or crypto—may not function as expected. In some cases, their usage can even prevent your project from deploying successfully.

However, many packages that rely on bundlers like Webpack (which provide browser-compatible polyfills) can still run without issues in the Worker environment.

Deployment Tips​

When setting up your instance for the first time, it's best to add both your sandbox instance and your production instance when running npm run authenticate. When you want to deploy your project to production, first deploy to your sandbox instance to preview the changes and then deploy to your production instance when you confirm the look and feel.

You should deploy early and often to your sandbox. Building a headless LMS and integrating with 3rd parties can introduce complexities if not done carefully.

Tip

If you didn’t add both instances when you ran npm run authenticate you can simply go to you ti-config.json file and enter the instance details there.

3rd Party Libraries​

Because Helium is fully open source and headless, you can easily incorporate third-party libraries and components to accelerate the creation of a world-class learning experience. However, keep in mind that Helium runs on Cloudflare Workers, which imposes certain compatibility constraints. Not all libraries will work seamlessly in this environment.

The simplest way to verify compatibility is to install the library and attempt a deployment to your Helium sandbox. If the deployment succeeds, the library is likely safe to use.

Writing GraphQL Queries​

GraphQL enables a “get exactly what you need” approach to data fetching. Instead of over-fetching or under-fetching, you define precise queries that return only the fields your application requires. This helps improve performance and maintain clean, maintainable data flows.

Each component in your application should ideally query only the data it needs. While it’s technically possible to write a large query in a root component and pass data down through props, this pattern can lead to bloated components, reduced flexibility, and slower performance. Structuring your queries around component boundaries promotes better modularity and aligns with GraphQL’s core strengths.

Querying CurrentUser​

Due to Cloudflare Worker Request Header Size limitations, we recommend querying the CurrentUser object directly rather than accessing it through PageProps.

This is because CurrentUser includes several large array fields—such as:

  • allocatedLicenses
  • allocatedLearningPaths
  • purchasedCourses
  • purchasedBundles
  • and others

When passed through headers, these fields may be truncated to stay within Cloudflare’s limits, potentially resulting in incomplete data. By querying CurrentUser directly for the properties you need, you ensure complete, up-to-date user data without risking truncation.