Advanced escape hatch

`@dep(...)`.

Most Nift projects should rarely—or never—need @dep. It exists for the exceptional case where an external file influences the output being built but Nift cannot discover that relationship through normal composition.

Do not start here.

If you are learning Nift, skip this page until you encounter a real dependency Nift cannot infer. Templates, tracked content and @input already establish the dependencies used by ordinary projects.

Normal dependencies are automatic

@input('templates/partials/header.html')
@content
@input('templates/partials/footer.html')

The template, tracked content and input files already participate in Nift's dependency bookkeeping. Do not mirror those relationships with @dep.

`@pathto` is not a reason to add `@dep`

<script src="@pathto('public/assets/app.js')"></script>
<img src="@pathto('public/assets/logo.svg')" alt="Logo">

These are project-aware paths. They do not need a ceremonial @dep beside them.

Where explicit dependencies help

Imagine another tool produces data/search-index.json. Your own build/preprocessing workflow uses that file to influence a page, but the file is never inserted with @input and Nift otherwise has no relationship it can follow.

@dep('data/search-index.json')

That declaration says: “this output depends on this external file even though you cannot infer why from the template graph.”

Multiple otherwise-invisible inputs

@dep(
  'data/navigation.json',
  'data/releases.json',
  'data/contributors.json'
)

The current v4 parser accepts one or more existing paths.

A decision test

Does @content establish the relationship?  → do not use @dep
Does @input establish the relationship?    → do not use @dep
Is this just a local asset via @pathto?    → do not use @dep
Can Nift otherwise infer the dependency?   → do not use @dep
External file genuinely affects output,
but Nift has no way to know?               → @dep may be appropriate

Think of @dep as an escape hatch, not a building block.

The fewer explicit dependencies you have to declare, the clearer the project remains. Prefer the ordinary project relationships whenever they describe what is actually happening.

Dependencies stay inside the project

@dep(...) is project build metadata, so its paths must remain inside the Nift project. Parent traversal or an absolute path escaping the project is rejected rather than allowing incremental state to depend on arbitrary files elsewhere on the machine.

RelatedIncremental builds →

Prefer sidecar JSON when the dependency is page metadata

If the relationship is clearer outside the authored template—for example dependencies produced by another tool or a page-level list of data inputs—use *.deps.json →. Both mechanisms feed the same incremental build model.

@dep(...).