$var shorthand |
No shorthand | |
|---|---|---|
| Syntax | '$uri.toUpperCase()' |
'r.uri.toUpperCase()' |
| Expands to | r.variables.uri.toUpperCase() |
used as-is |
| nginx-idiomatic | Yes — familiar $var references |
No — pure JS, foreign to nginx users |
| Access scope | r.variables.* only |
Full request object (r.uri, r.headersIn, r.args, etc.) |
| Ambiguity | $uri means r.variables.uri, not r.uri |
None — what you write is what runs |
| Conflicts | Clashes with JS ${...} template syntax |
No conflicts |
| Learning curve | Looks simple but hides the r.variables.* mapping |
Requires knowing the JS r API |
| Portability to files | Code breaks when moved to js_import — $uri is not valid JS |
Code works identically in inline and js_import files |
Pros of $var: familiar to nginx users, shorter for common variable lookups.
Cons of $var: only reaches r.variables.* (not r.uri, r.headersIn, etc.);
creates $ ambiguity with JS syntax; adds a textual substitution layer that may
surprise users. Inline expressions tend to grow — when a user moves the code to a
js_import file for easier development and debugging, the $var shorthand stops
working, forcing a rewrite from $uri to r.variables.uri.
Pros of no shorthand: no ambiguity, full API access, what you write is what
executes, seamless migration from inline to file.
Cons of no shorthand: more verbose for simple variable access
(r.variables.uri vs $uri).
| Expression | Template Literal | |
|---|---|---|
| Syntax | js_set $v 'expr'; |
js_set $v '`...${expr}...`'; |
| Wrapper | return (expr) |
return (`...`) |
| String building | '$uri + "_" + $host' |
'`${r.uri}_${r.host}`' |
| Readability | Operators and concatenation visible | Natural interpolation, reads like a string |
| nginx.conf parse | Works | Works (backticks are literal in '...') |
$var shorthand |
Compatible | Conflicts — $ is claimed by ${...} |
| Arbitrary JS | Single expression | Arbitrary expressions inside ${...} |
| Inline code concern | Moderate — clearly an expression | Higher — template strings can hide complex logic in ${...} blocks |
| New syntax to learn | None — standard JS expression | Backtick-inside-single-quote nesting |
Pros of expressions: no new syntax layer, $var shorthand works, clear
boundary (one expression), nginx users don't need to learn template literal
semantics.
Cons of expressions: string concatenation with + is verbose, quoting gets
awkward for strings within expressions (r.headersIn["Foo"] || "none").
Pros of template literals: natural string interpolation, cleaner when building
strings with embedded values.
Cons of template literals: incompatible with $var shorthand,
backtick-inside-single-quote nesting is unusual, blurs the line between config and
inline code, marginal benefit over expression syntax.