PascalCase, hooks in camelCase and everything else in kebab-case. A rule based on language cannot express that, because a component and a hook are both TypeScript. So naming rules are based on where a file lives: you set one convention for the whole workspace, then add path rules for the folders that differ.
File naming checks are Free.
snake_case, kebab-case, camelCase, and PascalCase. Iris Code checks the main part of the name, keeps known suffixes such as .test and .spec as they are, and suggests a replacement name.
In this example, files under a components folder use PascalCase, files under hooks or composables use camelCase, Python files use snake_case, and everything else uses kebab-case. Files in src/generated/ are not checked.
How Iris Code chooses a policy
For every file, Iris Code decides which rule applies in the same fixed order:- Built-in framework/generated-file exemptions and top-level
fileNaming.ignoreglobs (path patterns such assrc/generated/**) exclude the file. - Every matching
fileNaming.overridesrule is considered in the order you wrote them; the last matching rule wins. - If no path rule matches, an existing
languages.<language>.fileNamingpolicy is used as a backward-compatible fallback. - Otherwise the top-level
fileNaming.conventionapplies.
files list with at least one pattern, and a convention. It may also set scope. Overrides are only accepted in the top-level fileNaming object, so there is one ordered list of rules rather than several that compete.
Roll out without legacy noise
Turning on a naming rule in an existing project could flag hundreds of old files at once. To avoid that,fileNamingScope defaults to "new-files", which focuses on files added from now on.
- With a
.iris-baseline.json(a saved snapshot of the project), Iris Code checks only files that are not in that snapshot. A renamed file counts as new. - Without a baseline, Iris Code checks the whole scan. It shows the first 50 violations covered by
new-filesand states the full count. Findings from a matching rule withscope: "all"are never hidden by that limit of 50. - Set
"all"to check every file.
fileNaming holds the workspace convention, the paths to always skip, and the ordered path rules. fileNamingScope sets the default scope. A matching path rule can set its own scope; if it does not, an older per-language policy may set one; if neither does, fileNamingScope applies.
Built-in exemptions
Some files must keep a name set by a framework or a language, so Iris Code never checks them:- Next.js reserved files under
app/orpages/: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. This applies 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__.pyfiles. - Go conventions:
main.go,*_test.go, and generated*.pb.go. Platform suffixes such as_windows,_linux,_darwin,_amd64, and_arm64are kept, but left out when the rest of the name is checked. - 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.*, andesbuild.*.
ignore list adds your own paths to this list, written relative to the workspace. They are always skipped, even when a per-language policy applies. Ignore patterns in an older per-language policy are added on top. Windows backslashes are treated as forward slashes when matching.
Diagnostics and enforcement
A badly named file is marked in yellow in the VS Code Explorer, and an open file shows a rename hint at the top. Once a policy is set, these naming warnings also appear in the Problems panel by default, so the yellow marking shows instead of Git’s green colour for files it is not tracking yet. SetinlineDiagnostics.fileNaming to false to turn them off.
To accept an intentional exception, add iris-ignore-file: file-naming -- <reason> to the file.
Pro users can set gateMaxNamingViolations to limit the total number of naming violations allowed in a scan, so hooks and CI fail above it.
Fixing names
Iris Code can rename files to the suggested convention. Review the proposed name before applying it.Rename one file (Free)
Choose the naming hint above the code, the Quick Fix on the finding, or the Explorer right-click action. You can edit the suggested name before confirming. Iris Code updates TypeScript and JavaScript imports across the workspace that point at the renamed file. Use the toast’s Undo action or Iris Code: Undo Last Rename to restore the previous name. Other languages need extra review because a file name can affect references that Iris Code does not update:- Python: check
importstatements. - Ruby: check
require_relativepaths and the constant names Rails derives from the file name. - C#: check type names, namespaces and project references.
Rename several files (Pro)
Open the File Naming panel from the sidebar to see every violation and edit each target name. Rename selected files or all of them in one pass. Name collisions are skipped and reported. Commit your current work before a large batch so you have a clear point to return to.Adopting your existing convention
You do not have to configure naming by hand. After a workspace scan, if no policy is set, Iris Code works out the convention most of your files already follow and offers to adopt it:- A Naming Insight card in the sidebar shows the most common convention (for example, “78% of your files use kebab-case”). It is worked out again on every scan, so it stays accurate as files change.
- A notification makes the same suggestion once per workspace and does not repeat.
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.