Skip to content
Flareforge

Flareforge Lockfile

The flareforge-lock.json file is a critical component for maintaining the integrity and determinism of your generated application. It resides at the root of your project and should be committed to version control.

The file’s primary function is to map every file generated by the Flareforge engine to a unique SHA256 content hash. This creates a cryptographic signature of the entire generated codebase at a specific point in time.

An example entry in the lockfile appears as follows:

{
  "app/components/asset-upload.tsx": "de3d104babdd8d190dc60c6f5d99d929bb65bf505c8953c69a05247fec77af08",
  "database/schema.ts": "799119a9546bd16f3cf260ac81784e6e358803bbe26684f9d981b92c6835523b",
  ...
}

By tracking these hashes, Flareforge ensures that the code running in development and deployed to production is exactly what the framework intended to generate based on your configuration and its internal templates.

Hash Drifting

Section titled “Hash Drifting”

A hash mismatch, or “drifting,” occurs when the content of a generated file in your .flareforge directory has been modified, and its current hash no longer matches the hash recorded in flareforge-lock.json.

This integrity check is performed during the build process (flareforge build) to prevent the deployment of unintended or inconsistent code.

When a mismatch is detected, the build will fail, and an error message will be displayed explaining the issue.

Causes

Section titled “Causes”

A file can drift from its locked state for several reasons:

  1. You have deliberately modified the main flareforge.jsonc configuration, which results in different generated output.
  2. A generated file within the .flareforge directory was edited directly. This is discouraged, as these changes will be overwritten.
  3. An update to the flareforge framework itself introduced changes to its code generation logic or internal templates, resulting in new file contents.
  4. A change in a dependency that affects the code generation pipeline has altered the output.

How to Resolve

Section titled “How to Resolve”

The resolution depends on whether the change was intentional.

This occurs when you update a template or configuration and expect the generated code to change. To resolve this, you must update the lockfile with the new, correct hashes.

Run the codegen command:

Terminal window
npx flareforge codegen