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, add both your sandbox and production instances when running npm run authenticate. Deploy to sandbox first to preview changes, then deploy to production when confirmed.
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.
If you didn't add both instances when you ran npm run authenticate, you can add them directly to your ti-config.json file.
3rd Party Libraries
Because Helium is fully open source and headless, you can easily incorporate third-party libraries. However, keep in mind that Helium runs on Cloudflare Workers, which imposes certain compatibility constraints.
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. Each component 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.
Querying CurrentUser
Due to Cloudflare Worker Request Header Size limitations, we recommend querying the CurrentUser object directly rather than accessing it through PageProps.
CurrentUser includes several large array fields—such as allocatedLicenses, purchasedCourses, purchasedBundles, and others. When passed through headers, these fields may be truncated. By querying CurrentUser directly for the properties you need, you ensure complete data.