Best Practices: Naming Conventions in React Code Development
Consistency in variable types. Consistency in variable names. Consistency in methodology. Here is the React naming conventions guide I've developed over the years.
In every computer science course, in every class on software engineering fundamentals, the topic of "consistency" arises. Consistency in variable types. Consistency in variable names. Consistency in methodology, period.
As I've developed code, and especially in my time with React, I've taken that knowledge with me and applied it to my tasks. Consistency irons out the endless series of wrinkles I come across in development exercises. And for good reason. Those wrinkles I've ironed out saved me endless headaches in trying to backtrack and locate the source of an error, for instance. (And who doesn't want to avoid headaches?)
There are no true shortcuts in software development. Maybe the wrinkle saves you time, but only in the short-run. Eventually, you have to pay the engineering debt. And if history is a true indicator, that engineering debt grows with compounded interest quite quickly. Most of that interest is repaid in units of time.
So, let's dig into this topic and avoid a lot of that time cost.
File naming conventions
Since I've been developing in React, I'll keep my examples in terms of React. But they apply to software engineering in general and should be well-considered by any software engineer.
Here is the React naming conventions guide I've developed after performing some research, incorporating sets of best practices, and adapting it all to my personal taste:
1. In almost all cases , use PascalCase for component files.
Among all of the conventions I'll mention in this article, PascalCase is the best at hinting at words. Each word is capitalized. You can easily scan names and identify that which you intend to investigate. ThatPeskyLongNamedComponentThatJustDoesntSeemToEnd is, at least to me, easily readable at-a-glance, even though it's long. It requires a minimal number of characters to provide its identity, and there's no question where one word begins and the other ends.
... but is that really true?
Well, sort of. There is one exception: acronyms. So let me clear.
For acronyms, I've found it to be easier to identify the component's usage (as a file name or in code) by capitalizing every lettter of the acronym.
For example:
SomeCTAThing, NOT SomeCtaThing
Why? Because, above all, we actually aren't breaking spec by doing this. In fact, I'd say that we're enforcing spec by doing this. Best practice suggests capitalization of every word in a component's name. "CTA" is an acronym, a single-letter usage of each word in a name (or, think of it as a list).
A "CTA" is a "Call To Action".
So, SomeCTAThing is really "some call-to-action thing". It fits best practices, and it \ahem\ calls out to me more easily in a file list, a list of components in a front-end design layer, etc.
Let me know whether this (not-quite-un-)conventional usage works for you.
2. Use camelCase for function files.
This is appropriate for both single-function files (someFormalAction()) or a collection within a file (someUtilityAction() within util.ts). It's familiar to anyone who's already gone through a beginner course, so why break spec?
Some things that fall into this category:
- React hooks (
useSomeUtilityHook()) lib/*functions
3. Use kebab-case for all other files.
The hyphen between words is effective in hinting to the eye, and the lack of capitalization within the file name suggests the file doesn't go with something that is class-like (such as a component) or a non-component function (such as a page). It also adheres to the notion that would be absurd to dedicate a file to a single variable (and accordingly use camelCase for its file!).
Some things that should be kebab-cased:
- Front-end page names (
/app/some-page-location/page.tsx) - Stylesheets (
some-stylesheet-name.css) - Type definition files (
some-collection-of-type-definitions.ts)
4. Use strictly-consistent nomenclature.
Just as it's extremely important to ensure your directory structure is self-explanatory, you should also have extremely consistent file names (and names of components, functions, pages, etc.).
Consistent suffixes
You're developing for the front-end, which has code for individual pages. There's one for the home page, one for an About page, one for the blog, one for the contact form, etc. Use consistent naming, such as HomePage(), AboutPage(), BlogPage(), and ContactPage(). Using the suffix Page provides you a very simple hint in any errors to your console: if you see Page at the end of the culprit's name, you know it's a page!
No need to look in your /components folder when trying to find it.
No need to question it's purpose, either. It's a page. Because you named it so.
Consistent prefixes
Similarly, use consistent classification in your names. If it's part of the home page structure, prefix it with Home. If it's part of the blog structure, prefix it with Blog. And so on.
This avoids so many headaches at every phase of the development cycle. (Stack traces, anyone?)
Consistency is key
If every piece of code belongs somewhere, then (extremely) consistent nomenclature ensures that:
- Every piece of code has a family (prefix)
- Every piece of code has a purpose (suffix)
- Every piece of code has a unique identity (middle)
Conclusion
As I continue my journey in development, I'll inevitably experience more headaches than I ever imagined I would (!), but I know that I will have preemptively resolved a lot of them by using consistent nomenclature. I won't have to wonder which piece of code caused an error, which file it belongs to, or where that file is located.
Solve a lot of your headaches upfront by using consistent nomenclature. You'll thank yourself later!
