Javascript has never been so popular. In fact, today you can use it to do almost everything. However, JavaScript is not the only thing you need for a successful project. At least, you need to combine your JS code with a source control tool. This will allow you to keep track of all the changes in your project. When it comes to source control, the best tool out there is git. In this article, we see the best way to integrate JS + Git.
About Git
If you need to use Git, you need to know Git. Most developers already do, but in case you don’t, we have a quick intro for you. Otherwise, just scroll to the next section.
Git is a software to exchange source code between your workstation and a server. The server, the git server, will keep track of the versioning. In other words, it will keep track of how files change over time. To implement source control with git, you need a git server and the git software installed on your PC.
Luckily for us, there are many “As-a-Service” providers of git servers online. If your project is open-source, the best way to go is GitHub.com. Instead, if you want to keep the source code private, you can go with Microsoft Azure Repos. Both are free options.
Installing the client is also easy. Simply download it from here and install it. Then, you will be able to call the git command from the prompt.
Something more on Git and .gitignore
With Git, you have to push your files to the git server. Every time you do, your entire project folder will be uploaded to the server. However, you may want to exclude some files that you have in the folder. To do that, you can use the .gitignore file. This is a simple text file that lists all the file names you wish to exclude from your source control.
JS + Git Best Practices
Setup
The first thing you want to do for JS + Git is setting up your project folder for Git. Open the command prompt, and navigate to the folder containing your existing project. If you are starting out, simply create a new folder that will contain the project. Then, give the following command to init the project.
git initThis will initialize the folder for git usage. This process is the same for all programming languages, not only Javascript. Once the command finishes, you will see the .git folder and the .gitignore file. Git automatically creates the two, as they are needed for Git operation.
Now, it is time to discover the best practices of Javascript and Git. As you will see, they basically indicate what to put in the source control, and what not to. Besides that, Git is a simple tool that works in the same way for all programming languages and projects.
Include in the project (NEVER put in .gitignore)
Below the list of files and folders that should always be part of your source control. Those files are your project, and you want to push them to the server. Because of that, you should never list them inside the .gitignore file, otherwise they will be excluded.
- Actual source code – this is your actual project, the javascript files that make your application. Obviously, you need to have them in your source control.
- package.json – this file lists all the first-line dependencies you have in your project. You want to keep track of how dependencies change over time so that if something breaks after an update you know where to look.
- package-lock.json – this file lists the full dependency tree of your project. In other words, it not only contains your dependencies, but also the dependencies-of-dependencies. It is crucial to keep track of how dependencies evolve over time. If you want to learn more about this file and its relation with Git, I suggest reading What is package-lock.json? and Should I include package-lock.json in source control? posts.
- .env.testing – If you have such a file, it should describe a self-contained environment to run tests on your project. This must not include references to external resources, but rather allow any machine to run the tests of your project as standalone.
- Unit and feature tests – every time you download your project from the server on a new machine, you want to test everything is working as expected. Thus, you should always include both unit and feature tests.
Exclude from the project (put in .gitignore)
Instead, below we have the list of files and folders you should exclude from source control. These do not represent your project, and because of that you should include them in the .gitignore file.
- Automatically generated files – All files that your code generates automatically (e.g. after compiling assets) are not part of your project. Of course, the exception to that are package.json package-lock.json. Even if these files are generated automatically, you should always include them in your source control.
- IDE Settings – Developers like to work with complex text editor, as they allow them to focus on the code and not on other stuff around it. Modern IDEs allow developers to customize the appearance and functionalities on a per-project basis, and they do that by adding a folder inside the project root. That folder contains the settings the developer want to use for that project. That is not your project, and you should always exclude it. Furthermore, think the hassle if you forget to exclude and your colleagues get their settings changed when they download the last version of the code.
- .env – This file, if you have it, describes the environment of your machine. It defines your own machine, not your project, so always exclude it.
Wrapping things up
Setting up JS + Git for your project is simple. Despite that, you should consider the best practices when implementing it. We summarized such practices in this article, but we can summarize them more as follows (TL;DR). Always include in your source control files that describe your actual project, that are your source code. Exclude everything else.
Hopefully, this approach will help you simplify the management of your javascript projects. What do you think about it?
If you are also working with PHP, we have similar best practices for PHP + Git in this post.
