Files every open-source project should have

This is just how I like to go. Hence, I am sharing this with everyone. But if you do things differently and you don’t agree with what I have to say next then I respect your opinion.

Well, well, well! I see you are reading this post. That means you are intrigued and curious to know all the files you should have in your open-source project. Before I jump into this, I think you may also like my earlier article which you should definitely give a read if you are into Tailwind.

Tailwind CSS User? Read this!

Saad Irfan ・ Jun 24 '21

#tailwindcss #javascript #css #webdev

So that’s said, let’s jump into the highlight of this piece. Well, you see, I am not going to take much of your time. So if you just want to know the files, here is the list of them:

• .editorconfig
• .gitignore
• .prettierrc.json
• .npmrc
• License
• Code of Conduct
• Contributing
• Changelog
• Readme

I see you are still reading. That’s awesome. That means I have your undivided attention (at least I hope so). So while I have it, let me explain each of these files and why you should have them in your project.

🎩 .editorconfig

In my opinion, every open-source project should have this file. Why? Glad you asked. You are building an open-source project. You are using your code editor and that editor is configured according to your needs. Now someone else wants to contribute to your project. When they clone your repo and open it in their code editor, they will have different editor settings. And now if they open a PR, you will notice all the weird style changes in the code. 😐

This is where .editorconfig file comes into the picture. The settings that you have added to this file will ultimately be used by all the other code editors. So if you have this in your project, and someone then clones your project, they will also get a copy of this file that has all the editor settings, and if they have set indent style to spaces and you have set it to tabs then for this project, tabs will be used for indentation.

Here is an example of the contents of this file:

root = true

[*]
indent_style = tab
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true

Handy. Right?!

🏗 .gitignore

I am not going to explain this file much because I know you are a developer and if you are here, then you must have heard about this strange place called GitHub where all the developers put their work on display. And you must also have used git for version controlling your software.

Well if you have this file in your project then git will ignore all the files or folders you add to this file. Since you never commit your node modules to GitHub, you can just node modules inside this file and you are gold. Git will just ignore it now and you won’t see it when you write git status in your terminal. 🥂

Here is an example of the contents of this file:

node_modules/
/node_modules/

**.DS_Store*
ehthumbs.db

✨ .prettierrc.json

You need to write code that looks pretty and easy to read. Well, you can use prettier to do just this. Since I work mostly with JavaScript and Node.js for my open-source work, I always install Prettier as my dev dependency and add an additional script to my package.json file:

{
"scripts": {
        "format": "prettier --write \"./**/*.{js,json}\"",
    },

}

This script allows me to format my entire codebase using npm run format. If you carefully look at the script, you will notice that it actually contains a regular expression. You can modify it to include all the different file types you want to format.

Well, I still need to set some ground rules for Prettier to follow. Otherwise, again different code editors have different Prettier configurations set. So, in .prettierrc.json file, you define all the Prettier-related configurations. So if you run npm run format now, Prettier is going to follow this configs. ⚡️

Here is an example of the contents of this file:

{
    "trailingComma": "none",
    "singleQuote": true,
    "printWidth": 60,
    "useTabs": true,
    "tabWidth": 4,
    "semi": true
}

💥 .npmrc

If you want to set any npm-related configurations locally in your project, you can use this file to add them. For me, I just use this file to not generate a package-lock.json file. Well, because I don’t need it in production.

Here is an example of the contents of this file:

package-lock=false

🔑 License

Every and I mean EVERY open-source project should be licensed. This is a license file and the contents of it determine which license you want to use. Since I have authored more than 10 open-source tools, I often find myself going with the MIT license.

You can easily create this file by running a single command in your terminal:

npx license [license_name]

# for instance, npx license MIT

🧑🏻‍💼 Code of Conduct

This is another MUST have file for an open-source project. I think the name is quite self-explanatory. You can add a code of conduct in your project again using a single command. Just open your terminal and run this:

npx conduct

🙋🏻 Contributing

This is a markdown file that includes all the instructions that you want the potential contributors of your open-source project to follow. Everyone has different instructions. You can find the instructions that I usually go with here

‼ Changelog

Every open-source software should be properly versioned. With every new release, a new version comes in. This is another markdown file. It contains the changes that you have done across multiple versions of your project.

For instance, in version 1.0.0, you launched the beta version of your project. With version 1.1.0, you fixed a couple of bugs. Now you might want to add the changes you made to changelog.md file. So if anyone is using your tool, they can read this file and know instantly what exactly changed across a version. 💻

You can write your changelog file any way you want. Here is an example:

### v1.1.0

Fixed bug _____
Improve code of ____
Implemented feature ____

### v1.0.0

Implemented feature x that does ___
Implemented feature y that does ___
Implemented feature z that does ___

I am not going to get into how you should version your software. Maybe I will write another piece on it.

📖 Readme

I guess this is the most magical file in a project. The content you have in this file is shown in your project repository. So mainly, this file is used for documentation. And you should have great documentation if you want your project to be successful.

And there you have it, folks. These are all the files you should add to your open-source project. You can check this open-source project of mine where I have used all of these files. And while you at it, if you like it, don’t forget to star it. 😛

You can also follow me on GitHub where like many other magicians, all my magic lies.

Until next time, cheerios. 🤞🏻