Skip to main content
Most projects use more than one naming convention: components in PascalCase, hooks in camelCase, and everything else in kebab-case. A rule keyed on language cannot express that, since a component and a composable are both TypeScript. Naming rules are therefore keyed on where a file lives. Set a fallback for the workspace, then add path rules for the directories that differ. File naming checks are Free.
Valid conventions are snake_case, kebab-case, camelCase, and PascalCase. Iris checks the file stem, preserves known suffixes such as .test and .spec, and suggests a replacement name.

​
How Iris chooses a policy

For every file, Iris applies one deterministic precedence order:
  1. Built-in framework/generated-file exemptions and top-level fileNaming.ignore globs exclude the file.
  2. Every matching fileNaming.overrides rule is considered in declaration order; the last matching rule wins.
  3. If no path rule matches, an existing languages.<language>.fileNaming policy is used as a backward-compatible fallback.
  4. Otherwise the top-level fileNaming.convention applies.
An override requires a non-empty files glob array and a convention. It may also set scope. Override lists are valid only in the top-level fileNaming object, so there is one ordered rule list rather than nested precedence systems.

​
Roll out without legacy noise

fileNamingScope defaults to "new-files".
  • With .iris-baseline.json, Iris checks paths not present in the baseline. A renamed path counts as new.
  • Without a baseline, Iris checks the whole scan. It shows the first 50 violations governed by new-files and discloses the full count; findings from a matching rule with scope: "all" are never hidden by that rollout cap.
  • Set "all" to check every file explicitly.
Top-level fileNaming supplies the workspace default, absolute ignores, and ordered path rules. fileNamingScope is the rollout default. A matching path rule can set scope; otherwise a legacy language fallback may set it; when neither does, fileNamingScope applies.

​
Built-in exemptions

Iris always exempts:
  • Next.js reserved files under app/ or pages/: page, layout, route, loading, error, global-error, not-found, template, default, middleware, instrumentation, opengraph-image, sitemap, robots, manifest, _app, _document, and _error.
  • Files whose own name is a route construct or a private file: [id].tsx, [...slug].tsx, (group).tsx, and _/@-prefixed files. These apply to the file’s own name only - ordinary files inside a route-group (app), private _modals, parallel @slot, or dynamic [slug] folder are still checked against the convention.
  • Python conventions: __init__.py, __main__.py, conftest.py, setup.py, manage.py, and other __dunder__.py files.
  • Go conventions: main.go, *_test.go, and generated *.pb.go. Platform suffixes such as _windows, _linux, _darwin, _amd64, and _arm64 are preserved but removed before checking the stem.
  • Type declarations, universal entry files, and hidden paths: *.d.ts, index.*, dotfiles, and dotfolders.
  • Generated or vendored paths: vendor/, node_modules/, dist/, build/, .next/, __pycache__/, and *.generated.*.
  • Config-by-convention files such as next.config.*, tailwind.config.*, postcss.config.*, jest.config.*, vitest.config.*, vite.config.*, webpack.config.*, rollup.config.*, and esbuild.*.
The top-level ignore array adds absolute workspace-relative exclusions to this list, even when a language fallback applies. A legacy language policy’s ignore globs are additive. Windows separators are normalized before matching.

​
Diagnostics and enforcement

Violations receive a yellow decoration in the VS Code Explorer and a rename hint at the top of an open file. Naming diagnostics are on by default once a policy is configured so the Problems decoration can take precedence over Git’s green untracked-file color. Set inlineDiagnostics.fileNaming to false to opt out. Suppress an intentional exception with iris-ignore-file: file-naming -- <reason>. Pro users can set gateMaxNamingViolations to cap the scan-total count in hooks and CI.

​
Fixing names

Iris Code renames files to the suggested convention for you:
  • One file (Free). The naming CodeLens, the Quick Fix on the naming diagnostic, and the Explorer right-click menu all rename a file through an editable prompt. Iris Code updates TypeScript and JavaScript imports across the workspace, and every rename can be undone from the toast or the Iris Code: Undo Last Rename command. Renaming Python files does not rewrite import statements, renaming Ruby files does not rewrite require_relative paths or the constant names Rails derives from a filename, and renaming C# files does not rewrite type names, namespaces, or project references. Iris Code warns you in each case.
  • Every file (Pro). The File Naming panel (from the sidebar’s File Naming section) lists every violation with an editable target name. Rename selected files, or all of them, in one import-updating pass; name collisions are skipped and disclosed. Committing before a large batch is recommended.

​
Adopting your existing convention

You do not have to configure naming by hand. After a workspace scan, if no policy is set, Iris Code detects the convention your files already follow and offers to adopt it:
  • A persistent Naming Insight card in the sidebar shows the dominant convention (for example, “78% of your files use kebab-case”) and recomputes on every scan, so it stays accurate as files change.
  • A one-time toast per workspace surfaces the same suggestion without nagging.
Either one writes the fileNaming block into .irisconfig.json for you; the card clears once a policy exists. Iris Code only suggests a convention when your codebase clearly follows one.