File Naming for Cross-Platform Code

Recently, a colleague at Ensō encountered a time-consuming problem when moving an old Angular application to docker. After hours of figuring out why the application didn’t build, my colleague realized it was a case-sensitivity problem with directories and file names. My colleague’s learnings completely nailed a fundamental issue for cross-platform code.

The problem is that on most *nix systems (not HFS+ and default APFS on macOS), the file system is case sensitive and distinguishes between myFile, MyFileand myfile. Thus, if your code attempts to reference myfile but is named MyFile in the file system, it will fail on Linux. However, on Windows, which has a case-insensitive, case-preserving file system (unless case sensitivity mode is explicitly enabled), myfile, MyFileand MYFILE all refer to the same file. To prevent such issues, use only lowercase naming for files and directories.

In JavaScript and TypeScript, for example, it is common to use camelcase to name functions, e.g., myFantasticFunction(), and developers often name the containing file the same as the function name, e.g., myFantasticFunction.js. As you have learned, this can create issues. I advise naming such files in kebab case, e.g., my-fantastic-function.js.

To further illustrate, imagine you have two files, MyFantasticFunction.js and index.js. In index.js, you write the following code on your Windows system: import { myFantasticFunction } from './MyFantasticFunction'Then you decide to rename the MyFantasticFunction.js file to myFantasticFunction.js because you want to reflect the function name exactly. Everything is great! Windows don’t complain because it is case-insensitive, and your code doesn't break. But now you upload your code to a Linux system, and BOOM!!! Your code breaks. Thus, always lowercase. Always!