🎨 scadfmt

📌 What

An opinionated formatter for OpenSCAD code. It fixes indentation and spacing, puts blocks and statements on their own lines, and never joins lines or changes what the code does.

🤔 Why

Community contributions need one code style without style debates in review. Existing formatters rewrite code they do not understand (dropping operators, breaking include paths) or join hand-wrapped lines into very long ones. scadfmt only needs to know OpenSCAD's tokens, so new syntax rarely affects it, and it refuses to write output whose tokens differ from the input. See build-own-openscad-formatter-scadfmt.

🔧 How

📦 Install

Requires Python 3.11 or newer, no other dependencies.

pip install scadfmt           # from PyPI
pip install -e cmd/scadfmt    # from this repo

▶️ Usage

scadfmt format models/                  # format files in place, directories recursively
scadfmt format --check models/          # write nothing, exit 1 if a file would change
scadfmt format --diff part.scad         # write nothing, print a diff
scadfmt format - < in.scad > out.scad   # stdin to stdout

Exit codes: 0 clean, 1 files would change (--check), 2 error. On an error (unknown character, unbalanced brackets) the file stays untouched.

👀 Before and After

include<BOSL2/std.scad>
wall=2;// wall strength
height_units=3; // rack units
/**
 * Bracket holding a device of the given size.
 * center: centers the body on the origin
 */
module bracket(width=10,depth=20,center=false){
    size=[width,depth,wall*height_units];
    if(center){translate(-size/2)cube(size);}else{cube(size);}
    for(i=[0:2:width])
    translate([i,0,0])
    rotate([0,0,-90])
    #cylinder(h=wall,r=1);
}

becomes

include <BOSL2/std.scad>

wall = 2;          // wall strength
height_units = 3;  // rack units

/**
 * Bracket holding a device of the given size.
 * center: centers the body on the origin
 */
module bracket(width = 10, depth = 20, center = false) {
  size = [width, depth, wall * height_units];
  if (center) {
    translate(-size / 2) cube(size);
  } else {
    cube(size);
  }
  for (i = [0:2:width])
    translate([i, 0, 0])
      rotate([0, 0, -90])
        #cylinder(h = wall, r = 1);
}

📏 Rules

Comments (// or /* */) directly above a line belong to it, so a blank line added before that line goes above its comments. Lines are never joined and line length is never limited.

🙈 Opting Out

Lines between // fmt: off and // fmt: on stay as written, for example a hand-aligned matrix:

// fmt: off
identity = [
  1, 0, 0,
  0, 1, 0,
];
// fmt: on

🪝 Pre-commit

In another repository, install scadfmt from PyPI through a local hook:

- repo: local
  hooks:
    - id: scadfmt
      name: scadfmt
      entry: scadfmt format
      language: python
      additional_dependencies: [scadfmt==0.1.0]
      files: \.scad$

🖥️ VS Code

scadfmt vscode

Installs the Custom Local Formatters extension and makes scadfmt the default formatter for .scad files in .vscode/settings.json (of --workspace <folder>, default .), so Format Document (Shift+Alt+F) runs it.

⚠️ In a multi-root workspace, VS Code ignores the formatter list in a folder's .vscode/settings.json. Pass the .code-workspace file to --workspace there, so the settings go into it instead:

scadfmt vscode --workspace                        # asks about the nearest .code-workspace file in . or above
scadfmt vscode --workspace ../my.code-workspace   # no prompt

Declining the offered file, or having none, asks for a workspace file or folder.

It refuses to touch a settings file with comments; add the settings by hand then (in a .code-workspace file, inside its "settings" block):

"customLocalFormatters.formatters": [{ "command": "\"/path/to/python\" -m scadfmt format -", "languages": ["scad"] }],
"[scad]": { "editor.defaultFormatter": "jkillian.custom-local-formatters" }

For formatting on save, add "editor.formatOnSave": true to the [scad] block.

🔄 Keeping Up with OpenSCAD

HomeRacker pins OpenSCAD nightly. When a weekly nightly bump changes OpenSCAD's grammar, a Claude agent adapts scadfmt and its canary on the Renovate PR, and a maintainer approves the result. See agent-adapts-scadfmt-to-openscad-nightly. To do the same by hand, follow the scadfmt-adapt skill.

🧪 Tests

See TESTING.md. tests/canary/ holds a file using every OpenSCAD construct and its expected output; check.sh checks both against the pinned OpenSCAD. tests/ast_check.sh proves that formatting-only changes in a PR keep OpenSCAD's AST.

📚 References

• #177: introduce an OpenSCAD formatter
• build-own-openscad-formatter-scadfmt: why scadfmt exists and how it works
• agent-adapts-scadfmt-to-openscad-nightly: how scadfmt follows new OpenSCAD nightlies
• OpenSCAD language reference