Loopback: Config Files
Configuring your projects for multiple environments
After generating a project with Loopback you will notice a number of config files in the ./server directory. If you are just trying to get a api up and running, those files can be a lot to take in. This article is meant as an introduction to the config files created by Loopback CLI.
Some of the examples I will mention, include a school related data model i defined in my last article. If you are already familiar with the software, don’t worry about reading it. This series is loosely coupled so that you can jump in at any time.
Assumed Knowledge
I am going to assume you know what environment variables are, so if you don’t read about the simple and scalable solutions here.
Environments 🌿
Before we get into the different config files, I want to mention how to set your environment, and create environment specific settings.
This is important because inevitably your api will need to be tested, developed, and hosted all with different databases, https settings, and more. So setting up each of these environments is crucial.
Setting Your Environment
To specify the environment you are working in you need to set the NODE_ENV environment variable. There are many way of doing this. and the intro for some helpful links if you don’t know how.
For my use case I am using the scalable option of a .env file.
- Install dotenv
yarn add dotenv
2. Create .env and assign NODE_ENV to development
3. Initialize dotenv in your ./server/server.js
Creating Enviroment Specific Files
Now that we have our environment setup, it is time to create environment specific files. All config files will by default look in the standard file location, that is setup when you initialize a project. For Datasources this is ./server/datasources.json. If you want to specify a config file for a certain environment follow the ./server/configFile.{env}.json pattern.
An example of this can be seen in the following section. The right is the original generated datasource.json file, and the left is the development specific datasource file.
Js vs. JSON
Finally, don’t ever feel like you are bound to using JSON for your config files. In many cases Js files are better as they allow you to use environment variables, which are needed in production.
NOTE: Some config files require you to keep a base file that is JSON. Datasources is a good example. More on that soon!
Config Files ⚙️
Now comes the meat of this article. Each of the following sections will give you an look into the purpose of each of the different file.
dataSources.json
Datasource files take the most configuration, and are very important to your project, they allow you to configure how you are connecting to a datasource.
For our school example I will be creating three new datasource files, for the three environments listed above: development,test, and production. This article will focus on development, and testing and hosting will be covered soon.
I personally prefer as many files to be Js as possible, but there is a confusing error if you delete the base datasources.json.
To avoid this error I clear the base datasources.json, and just specify any additional datasources.
component-config.json
Components are official packages for Loopback. By default loopback-component-explorer is installed with the LoopbackCLI. It is the only one I have found needed in my projects, but feel free to view other components here!
It is recommended to disable the api explorer in production. This can be done by assigning the loopback-component-explorer field to null in the production version of component-config.json
config.json
Server settings can be configured from the config file. Go figure. There are three root options available.
- aclErrorStatus — configures the status code on rejected responses. 401(unauthorized) is the default, but in some cases 403(forbidden) might more accurately describe the condition.
- host
- legacyExplorer — configures whether disabled routes are shown in the explorer described in the component-config section.
- port
- remoting — configures http restrictions, like cors and max request size
- restApiRoot — configures the extension from which your api will be hosted. ‘./api’ is the default
middleware.json
By definition, middleware is a connecting component between separate parts of a project.
There are two middleware files that come with Loopback CLI. The development version allows for debugging and logging, which is turned off for production.
Personally, I have not found a need to change either of the middleware files, but if you ever need to configure CORS settings they are held under the initial section
model-config.json
This file controls not only how individual models are configured, but also where they are pulled from.
The _meta section is the only field that is not associated with a particular model. It holds an array of paths to existing models in your project.
Other than meta, models generally have two fields. dataSource, which is the dataSource that this model is stored in, and public, which is whether api routes should be generated for this model.
Conclusion
At this point in our school application, I haven’t adjusted much. Most config will come when we need datasources for testing and hosting, so stay tuned for those articles.
If you have any questions, on configuring Loopback feel free to reach out. I will do my best to help.
🤟Josh
Previous articles in this series.
