alexi_taylor
Back to blog
•
4 min read
File Naming Convention

File Naming Convention

Context

The health-activity-ui repo has not landed on a consistent allfile naming convention. Currently, there’s a mismatch of how files are named which leads to:

  • Confusion among developers of how files should be named.
  • A more arduous experience to search for and identify specific files.
  • A lack of readability to understand the content of a file at a glance.
  • Inconsistency.

By agreeing on a consistent file naming convention, we can adhere to a standard where:

  • Meaningful names of files will communicate their intent. For example, activity-list.component.tsx states that the file contains a React component that manages a list of activities.
  • At a glance, engineers can search for code quickly by looking at the file name for context.
  • We can provide readability and help with maintainability.

Decision

When it comes to naming files and directories, there are a few rules we need to follow.

  1. kebab-case: Uses lower case words separated by hyphens (dashes), e.g., foo-bar.
    1. All lowercase.
    2. Only letters, numbers, dashes (-), and ..
  2. Keep it descriptive and short. File names should be short and describe what the contents of the file are.
  3. Proper file extensions: Always use TypeScript (.ts) or TSX, React in TypeScript, (.tsx). There are a few exceptions, such as config files can be in .js or .json.
  4. File type suffix: The filename should include a suffix for the file type. Append the type of the file after the short and descriptive filename, e.g., .component.tsx, .models.ts, and etc. A list of file types:
    1. .component.tsx: React component.
    2. .styled.ts(x): Styled component.
    3. .models.ts: Interfaces, enums, types, or constants.
    4. .class.ts: TypeScript class.
    5. .api.ts: API functions.
    6. .utils.ts: Util functions.
    7. .spec.ts(x): Tests

File name

✅ Good

foo-bar.ts
foo.ts

❌ Bad

FooBar.ts
Foo.ts
foo_bar.ts

React Components: .component.tsx

✅ Good

foo-bar.component.tsx
foo.component.tsx

❌ Bad

FooBar.tsx
foo-bar.component.ts // <-- React files should always have .tsx extension
FooBarComponent.tsx

Styled Components: .styled.ts(x)

✅ Good

foo-bar.styled.ts
foo.styled.ts
foo.styled.tsx

❌ Bad

FooStyled.ts
styled.ts

Models: .models.ts

Extract all related interfaces, enums, types, and constants into its own file.

Always TS.

✅ Good

foo-bar.models.ts
foo.models.ts

❌ Bad

foo-bar.interface.ts
FooModels.ts
foo.models.tsx
foo.models.js

Class: .class.ts

Always TS.

✅ Good

foo-bar.class.ts
foo.class.ts

❌ Bad

FooClass.ts
foo-bar.class.tsx
foo.class.js

API Functions: .api.ts

✅ Good

foo-bar.api.ts
foo.api.ts

❌ Bad

FooApi.ts

Data Providers: .provider.tsx, .actions.ts, and .reducer.ts

✅ Good

foo-bar.provider.tsx
foo-bar.actions.ts
foo-bar.reducer.ts

❌ Bad

FooProvider.tsx
FooActions.ts
FooReducer.ts

Utils: .utils.ts

✅ Good

foo-bar.utils.ts
foo.utils.ts

❌ Bad

FooUtils.ts
foo.utils.tsx

Test Files: .spec.ts(x)

✅ Good

foo-bar.spec.ts(x)
foo.spec.ts(x)

❌ Bad

foo-bar.test.ts(x)
FooBar.spec.ts(x)

Exceptions

With all rules, there are some exceptions that break our naming convention:

  • README.md - markdown files should use ALL CAPS. Another example: CONTRIBUTING.md
  • An exception to our exception. Our ADRs are kebab-case and numerically ordered, e.g., 0001-foo-bar.md.
  • CODEOWNERS - All caps.

Consequences

  • Consistent file naming convention that engineers understand.
  • Communicates what a file is about, making it easier for others to scan files and understand the purpose of the file.
  • Provides a naming convention others can follow when creating a file.

Happy Coding 🚀