Troubleshooting Missing Stylus Mixin Output When Omitting Optional Arguments

Recognizable condition

After invoking a Stylus mixin without supplying optional arguments, the CSS rules that should be generated inside the mixin do not appear in the compiled output.

Cause / diagnostic table

Symptom	Possible cause
Missing rules	Mixin parameters lack default values, causing the mixin body to be skipped when arguments are omitted
Incorrect indentation	Mixin definition indented incorrectly, leading Stylus to treat it as a regular rule set
Variable shadowing	A local variable with the same name as a mixin parameter hides the intended value

Ordered checks

1. Verify that the mixin definition includes default values for all optional parameters (e.g., mixin-name($param = default)).
2. Confirm that the mixin call omits arguments only for those parameters that have defaults.
3. Inspect the indentation of the mixin block; it must be exactly two spaces (or a consistent tab) relative to the mixin declaration line.
4. Look for any variable re‑definitions inside the mixin that could shadow parameters.
5. Compile a minimal test file (test.styl) containing only the mixin and its call to isolate the issue.

Fixes tied to findings

• Add default values to missing parameters: change mixin-name($param) to mixin-name($param = 0) (or another sensible default).
• Adjust indentation to match Stylus’s whitespace rule (two spaces per level) and re‑run the build.
• Rename shadowed variables or use the arguments object to access the original parameter.
• If the mixin is imported from another file, ensure the import path is correct and that the imported file is not being overridden by a later definition with the same name.
• After applying a fix, recompile and verify that the expected CSS appears.

Concrete example

/* test.styl */
mixin button($bg = #fff)
  background $bg
  padding 10px

.button-primary
  +button()   /* call without argument */

Expected CSS after compilation:

.button-primary {
  background: #fff;
  padding: 10px;
}

If the .button-primary block is missing, follow the checks above.

Escalation criteria

If the mixin still fails to produce output after verifying defaults, indentation, and variable scope, enable Stylus debug mode to view the parsed AST:

stylus -d test.styl

Review the debug output for signs that the mixin was not recognized. Provide the Stylus compiler version (stylus --version) and a minimal reproducible example when filing an issue.

Limitations and verification

Stylus is whitespace‑sensitive; mixing tabs and spaces can silently break mixin detection, especially in editors that convert tabs to spaces differently. The behavior of default arguments changed between Stylus 0.42 (where omitted arguments caused an error) and 0.54+ (where they are treated as undefined unless a default is provided). Ensure you are using a recent version if you rely on omitted‑argument defaults.

To verify a fix, create a file verify.styl with a simple mixin that has a default argument, call it without arguments, and compile:

stylus verify.styl

Inspect the generated verify.css; the expected rule set should be present. If the rule appears, the diagnostic steps succeeded; otherwise repeat the checks, paying particular attention to indentation and version‑specific default‑argument handling.