File Naming Conventions: Keep Your Project Clean and Readable ✨

This content originally appeared on DEV Community and was authored by Damian Sire (Dev)

Ever jumped into an Angular project and felt lost in a sea of confusing file names? Consistent naming isn’t just about being tidy; it’s a cornerstone of professional, maintainable, and team-friendly code. When your file structure is predictable, you spend less time searching and more time coding.

Let’s break down some simple but powerful file naming conventions from the official Angular style guide that will make your life (and your teammates’ lives) much easier.

Separate Words with Hyphens (Kebab-Case)

This is the foundational rule. Always separate words in your file names with hyphens. This convention, often called kebab-case, is a standard in web development and makes file names easy to read.

For example, if you have a component class named UserProfileComponent, its file name should be:

user-profile.component.ts

This is much clearer and more conventional than userprofile.ts or user_profile.ts.

Name Test Files with `.spec`

Your unit tests are first-class citizens in your project and should be easy to find. The standard is to use the exact same name as the file you are testing, but with a .spec.ts suffix.

This pattern is instantly recognizable and is the default configuration for testing frameworks like Karma and Jest in the Angular ecosystem.

For our user-profile.component.ts file, the corresponding test file would be:

user-profile.component.spec.ts

Match the File Name to Its Contents

A file’s name should be a clear signpost to what’s inside. When a file contains a primary identifier, like a TypeScript class, the file name should be the kebab-case version of that identifier.

For instance, a file containing the class OrderHistoryService should be named:

order-history.service.ts

A quick tip: Avoid overly generic file names like helpers.ts, utils.ts, or common.ts. While tempting, these files often become a dumping ground for unrelated code, making them hard to maintain. If you have several unrelated helper functions, consider breaking them into separate, more specific files (e.g., string-formatters.ts, validation-rules.ts).

Group Component Files by Name

A typical Angular component is made up of several files: the TypeScript logic, the HTML template, and the CSS/SCSS styles. To keep these related files neatly grouped and easy to locate, they should all share the same base name.

Following our UserProfileComponent example, its complete set of files would look like this:

user-profile.component.ts (the component class)
user-profile.component.html (the template)
user-profile.component.scss (the styles)

This makes it incredibly simple to find all the pieces of a single component.

What if a component has multiple style files? Just append a descriptive word. For example, you might have styles specific to different themes or sections:

user-profile-light.scss
user-profile-dark.scss

Why Does This Matter?

Following these conventions brings huge benefits:

Readability: Your project becomes instantly easier to scan and understand.
Findability: You can find any file you need quickly, without guesswork.
Consistency: It creates a professional and predictable structure, which is crucial when working on a team.
Tooling: Many CLI commands and IDE extensions rely on these conventions to generate, find, and link code correctly.

By adopting these simple naming rules, you’re not just organizing files—you’re building a more professional, scalable, and enjoyable Angular application.

Happy coding!