Answer to the Core Question
In Handlebars 4.x, block parameters are not automatically added to the hash of nested helpers. The compiler treats them as local variables only for the block body. If a nested helper needs to see them, you must pass them explicitly, e.g. {{nestedHelper @index @value}} or {{nestedHelper @blockParams}}.
Confirmed Facts
- Block parameters are scoped to the block in which they are declared.
- There is no runtime flag or helper‑API switch that changes this default behaviour.
- Passing block parameters to a nested helper requires an explicit reference in the template.
Impact on Helper Signatures
If a nested helper expects a hash shape that includes block parameters, you must construct that hash yourself:
{{#each items as |item idx|}}
{{nestedHelper attr=item key=idx}}
{{/each}}
Without this explicit mapping the helper receives only the hash arguments you supply in the call, not the block parameters.
Backward‑Compatibility Considerations
- Future Handlebars releases that change this scoping rule would break any templates that rely on implicit propagation of block parameters.
- Because the current behaviour is well‑documented, the risk of accidental breakage is low unless a breaking change is introduced.
- If you plan to upgrade, run the
handlebars --check tool or a test harness to ensure nested helpers still receive the expected arguments.
Practical Limits on Block Parameter Count
While Handlebars itself imposes no hard cap, JavaScript engines limit how many arguments a function can accept. In practice:
- V8 (Node.js & Chrome) tolerates up to ~255 arguments before performance degrades or errors appear.
- Declaring more than 200–250 block parameters in a single block can trigger compilation warnings or stack‑overflow errors.
- Keep block parameter lists short (10–20 is a safe range) for readability and engine stability.
Quick Test Pattern
// Node.js example
const Handlebars = require('handlebars');
const template = Handlebars.compile('{{#each list as |p0 p1 p2|}}{{p0}}{{p1}}{{p2}}{{/each}}');
console.log(template({list: [['a','b','c']] }));
Increase the number of declared parameters incrementally until compilation slows or errors appear.
What to Do If You Encounter Issues
- Reduce the number of block parameters per block.
- Explicitly pass only the parameters the nested helper needs.
- Test in the target runtime (Node.js version or browser) to confirm the safe threshold.
Missing Diagnostic Detail
To give a more precise recommendation, could you share which JavaScript runtime (Node.js version or browser) you are targeting?
handlebars
nodejs