{"id":15873765,"url":"https://github.com/boostrjs/boostr","last_synced_at":"2025-08-31T05:41:11.620Z","repository":{"id":65077758,"uuid":"343241419","full_name":"boostrjs/boostr","owner":"boostrjs","description":"Build and deploy your Layr apps","archived":false,"fork":false,"pushed_at":"2024-03-25T13:13:01.000Z","size":3001,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-26T13:21:01.274Z","etag":null,"topics":["app","application","backend","build","create","database","deploy","deployment","develop","framework","frontend","full-stack","javascript","layr","test","tool","typescript"],"latest_commit_sha":null,"homepage":"https://boostr.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boostrjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-28T23:50:16.000Z","updated_at":"2024-08-24T13:44:41.168Z","dependencies_parsed_at":"2024-03-30T20:01:07.640Z","dependency_job_id":null,"html_url":"https://github.com/boostrjs/boostr","commit_stats":{"total_commits":157,"total_committers":1,"mean_commits":157.0,"dds":0.0,"last_synced_commit":"166755a3eb42314956e53078408acab70e9d76a6"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boostrjs%2Fboostr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boostrjs%2Fboostr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boostrjs%2Fboostr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boostrjs%2Fboostr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boostrjs","download_url":"https://codeload.github.com/boostrjs/boostr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243802942,"owners_count":20350316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app","application","backend","build","create","database","deploy","deployment","develop","framework","frontend","full-stack","javascript","layr","test","tool","typescript"],"created_at":"2024-10-06T01:06:19.567Z","updated_at":"2025-03-16T04:30:43.750Z","avatar_url":"https://github.com/boostrjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"assets/boostr-logo-with-icon.svg\" width=\"200\" alt=\"Boostr\"\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\u003c/p\u003e\n\n## Overview\n\nBoostr is a companion tool for [Layr](https://layrjs.com).\n\nIn a nutshell, Boostr takes care of everything you need to build and deploy a Layr app so you can focus on what really matters — your app's code.\n\n## Features\n\nHere are the main features provided by Boostr:\n\n- App templates so you can bootstrap an app with a single command\n- Fully managed local development environment:\n  - Automatic frontend build and refresh\n  - Automatic backend build and restart\n  - Local development database (limited to [MongoDB](https://www.mongodb.com/) for now)\n- Configuration management:\n  - Environment variables with inheritance and cross-service references\n  - Multiple stages (e.g., `'development'`, `'staging'`, and `'production'`)\n  - Public and private configurations\n- Database migrations (limited to [MongoDB](https://www.mongodb.com/) for now)\n- Serverless deployment with a single command (limited to [AWS](https://aws.amazon.com/) for now)\n\n## Getting Started\n\n### Prerequisites\n\n- You use a Mac with a recent version of macOS. Everything should work fine on Linux, but we haven't tested it yet. It may work on Windows, but we haven't tested it and don't plan to provide support for now.\n- You have [Node.js](https://nodejs.org/) v16 or newer installed.\n\n### Installation\n\n```sh\nnpm install --global boostr\n```\n\n\u003e **Note**: Installing an NPM package globally is usually not recommended. But it's not a problem in this case because each app managed by Boostr uses a local Boostr package which is automatically installed. So the global Boostr package can be seen as a shortcut to the local Boostr packages installed in your apps, and, therefore, you can have different apps using different versions of Boostr.\n\n### Creating a Layr App\n\nBoostr provides an `initialize` command to bootstrap an app from a template.\n\nFor example, you can bootstrap a Layr web app using TypeScript with the following commands:\n\n```sh\nmkdir my-app\ncd my-app\nboostr initialize @boostr/web-app-ts\n```\n\nThen, you can open the `my-app` directory in your favorite [IDE](https://en.wikipedia.org/wiki/Integrated_development_environment) to explore the initial codebase.\n\n\u003e **Note**: You can use any IDE you want, but if you use [Visual Studio Code](https://code.visualstudio.com/), you can profit from the VS Code configuration included in the [supported app templates](#boostr-initialize-template-options). Otherwise, you may have to set up your IDE to get a suitable configuration.\n\nCheck out the [`initialize`](#boostr-initialize-template-options) command for details.\n\n### Starting a Layr App\n\nYou can start your app in development mode with the following command:\n\n```sh\nboostr start\n```\n\nIn the case of a web app, the terminal should output something like this:\n\n```\n[database] MongoDB server started at mongodb://localhost:18160/\n[backend] Build succeeded (bundle size: 2.06MB)\n[backend] Component HTTP server started at http://localhost:18159/\n[frontend] Build succeeded (bundle size: 1.34MB)\n[frontend] Single-page application server started at http://localhost:18158/\n```\n\n\u003e **Notes**:\n\u003e\n\u003e - The TCP ports used for each [local development URL](#local-development-urls) were randomly set when the `initialize` command was executed to create your app in the [previous section](#creating-a-layr-app). So, it's normal if they are different for your app.\n\u003e - Don't be freaked out by the size of the generated bundles in development mode. When you deploy your apps, the generated bundles are a lot smaller.\n\nThe last line in the terminal output should include an URL you can open in a browser to display your app.\n\nCheck out the [`start`](#boostr-service-start-options) command for details.\n\n### Deploying a Layr App\n\nFirst, make sure that your frontend and backend Boostr configuration files (`frontend/boostr.config.mjs` and `backend/boostr.config.mjs`) specify the URLs you want to use for your app.\n\nSo, if you just created a web app with the [`initialize`](#boostr-initialize-template-options) command, replace all the occurrences of `'example.com'` with your domain name (e.g., `'awesome.app'`) or subdomain name (e.g., `'project1.awesome.app'`).\n\nThen, run the following command to deploy your app to production:\n\n```\nboostr deploy --production\n```\n\nCheck out the [`deploy`](#boostr-service-deploy-options) command for details.\n\n## Configuration Files\n\nA Layr app managed by Boostr is usually composed of different services, and each service is associated with a configuration file named `boostr.config.mjs`.\n\nFor example, a typical web app comprises the following directories and files:\n\n- `boostr.config.mjs`: [Application service](#application-service) configuration file (also called \"root configuration file\").\n- `frontend`:\n  - `boostr.config.mjs`: [Web-frontend service](#web-frontend-service) configuration file.\n- `backend`:\n  - `boostr.config.mjs`: [Backend service](#backend-service) configuration file.\n- `database`:\n  - `boostr.config.mjs`: [Database service](#database-service) configuration file.\n\n\u003e **Note**: The name of the directories (e.g., `frontend`, `backend`, `database`) are specified in the root configuration file, so they can be anything you want.\n\nAny configuration file is a JavaScript ESM module exporting a function (as `default` export) which should return a plain object representing the configuration.\n\nHere's an example of a simple root configuration file:\n\n```js\nexport default () =\u003e ({\n  type: 'application',\n\n  services: {\n    frontend: './frontend',\n    backend: './backend',\n    database: './database'\n  }\n});\n```\n\nThe `type` property specifies a string representing the type of the service and is required for each configuration file. In the case of a root configuration file, the value of `type` should be `'application`'.\n\nThe `services` property specifies an object allowing to match the name of the services used by the app with the path of the directories containing these services.\n\n### Application Service\n\nThe application service (also called \"root service\") is represented by a configuration file that specifies all the services used by your app and some general properties such as [environment](#environment-variables) and [stages](#stages).\n\nHere's an example of an application service configuration file:\n\n```js\n// boostr.config.mjs\n\nexport default () =\u003e ({\n  type: 'application',\n\n  services: {\n    frontend: './frontend',\n    backend: './backend',\n    database: './database'\n  },\n\n  environment: {\n    APPLICATION_NAME: 'Layr App',\n    APPLICATION_DESCRIPTION: 'A Layr app managed by Boostr.'\n  },\n\n  stages: {\n    staging: {\n      environment: {\n        NODE_ENV: 'production'\n      }\n    },\n    production: {\n      environment: {\n        NODE_ENV: 'production'\n      }\n    }\n  }\n});\n```\n\nThe object returned by the exported function contains the following properties:\n\n- `type`: Specifies the type of service, which should always be `'application'` in the case of an application service.\n- `services`:\n  - `frontend`: Specifies the directory's path (`./frontend`) of a web-frontend service simply named `'frontend'`.\n  - `backend`: Specifies the directory's path (`./backend`) of a backend service incidentally named `'backend'`.\n  - `database`: Specifies the directory's path (`./database`) of a database service incidentally named `'database'`.\n- `environment`: An object allowing you to define some global [environment variables](#environment-variables).\n- `stages`:\n  - `staging`: An object allowing you to define some properties when the `'staging'` [stage](#stages) is used.\n  - `production`: An object allowing you to define some properties when the `'production'` [stage](#stages) is used.\n\n### Web-Frontend Service\n\nA web-frontend service is represented by a configuration file that specifies some properties related to the nature of a web frontend and some general properties, such as [environment](#environment-variables), [stages](#stages), and [dependsOn](#service-dependencies).\n\nHere's an example of a web-frontend service configuration file:\n\n```js\n// frontend/boostr.config.mjs\n\nexport default ({services}) =\u003e ({\n  type: 'web-frontend',\n\n  dependsOn: 'backend',\n\n  environment: {\n    FRONTEND_URL: services.frontend.url,\n    BACKEND_URL: services.backend.url\n  },\n\n  rootComponent: './src/index.ts',\n\n  html: {\n    language: 'en',\n    head: {\n      title: services.frontend.environment.APPLICATION_NAME,\n      metas: [\n        {\n          name: 'description',\n          content: services.frontend.environment.APPLICATION_DESCRIPTION\n        },\n        {charset: 'utf-8'},\n        {name: 'viewport', content: 'width=device-width, initial-scale=1'},\n        {'http-equiv': 'x-ua-compatible', 'content': 'ie=edge'}\n      ],\n      links: [\n        {\n          rel: 'icon',\n          href: '/boostr-favicon-3NjLR7w1Mu8UAIqq05vVG3.immutable.png'\n        }\n      ]\n    }\n  },\n\n  stages: {\n    development: {\n      url: 'http://localhost:10742/',\n      platform: 'local'\n    },\n    staging: {\n      url: 'https://staging.example.com/',\n      platform: 'aws',\n      aws: {\n        region: 'us-east-1',\n        cloudFront: {\n          priceClass: 'PriceClass_100'\n        }\n      }\n    },\n    production: {\n      url: 'https://example.com/',\n      platform: 'aws',\n      aws: {\n        region: 'us-east-1',\n        cloudFront: {\n          priceClass: 'PriceClass_100'\n        }\n      }\n    }\n  }\n});\n```\n\nThe object returned by the exported function contains the following properties:\n\n- `type`: Specifies the type of service, which should always be `'web-frontend'` in the case of a web-frontend service.\n- `dependsOn`: Specifies that the `'frontend'` service depends on the `'backend'` service. See [\"Service Dependencies\"](#service-dependencies) for details.\n- `environment`: An object allowing you to define some [environment variables](#environment-variables) specific to the `'frontend'` service. Note that `'FRONTEND_URL'` and `'BACKEND_URL'` are determined according to some service properties fetched from the `services` parameter of the configuration function. See [\"Service Property References\"](#service-property-references) for a detailed explanation.\n- `rootComponent`: Specifies the file's path implementing the root Layr component of your web frontend.\n- `html`: An object allowing you to customize the `index.html` file automatically generated by Boostr. See [\"Autogenerated `index.html` File\"](#autogenerated-indexhtml-file) for details.\n- `stages`:\n  - `development`: An object allowing you to define some properties when the `'development'` [stage](#stages) is used.\n    - We define the `url` property so you can access the web frontend locally (see [\"Local Development URLs\"](#local-development-urls) for details).\n    - We set the value of the `platform` property to `'local'` to indicate that Boostr should manage a local frontend server.\n  - `staging` and `production`: An object allowing you to define some properties when the `'staging'` or `'production'` [stage](#stages) is used.\n    - We set the value of the `url` property to an URL where Boostr can deploy the web frontend (see [\"Deployment URLs\"](#deployment-urls) for details).\n    - We set the value of the `platform` property to `'aws'` to indicate that Boostr should use [AWS](https://aws.amazon.com/) as a deployment target.\n    - Optionally, we can specify an `aws` object to customize the AWS configuration (see [\"Web-Frontend AWS Configuration\"](#web-frontend-aws-configuration) for details).\n\n#### Autogenerated `index.html` File\n\nIn the codebase of a Layr web app managed by Boostr, you will not see any `index.html` file because this file is autogenerated.\n\nWe made this choice so that Boostr could abstract away the execution environment (e.g., browser, [React Native](https://reactnative.dev/), or [Electron](https://www.electronjs.org/)) in which the app runs.\n\nSo, your app should be mainly composed of configuration files and Layr components.\n\nHowever, in most cases, it is necessary to customize the `index.html` file so your web app can have, for example, a title and a favicon.\n\nAs seen in the [above example](#web-frontend-service), you can do so by setting the `html` property in your web-frontend service configuration file.\n\nThe `html` property should be an object composed of the following properties:\n\n- `language`: A string specifying your web app's language (e.g., `'en'`). When the `index.html` file is autogenerated, this property determines the value of the `lang` attribute of the `\u003chtml\u003e` tag (e.g., `\u003chtml lang=\"en\"\u003e`).\n- `head`:\n  - `title`: A string specifying your web app's title (e.g., `'My Awesome App'`). When the `index.html` file is autogenerated, this property determines the content of the `\u003ctitle\u003e` tag in the `\u003chead\u003e` section (e.g., `\u003ctitle\u003eMy Awesome App\u003c/title\u003e`).\n  - `metas`: An array of objects specifying the attributes of some `\u003cmeta\u003e` tags to include in the `\u003chead\u003e` section of the autogenerated `index.html` file. See an example of use in the [above example](#web-frontend-service).\n  - `links`: An array of objects specifying the attributes of some `\u003clink\u003e` tags to include in the `\u003chead\u003e` section of the autogenerated `index.html` file. See an example of use in the [above example](#web-frontend-service).\n  - `style`: A string specifying the content of a `\u003cstyle\u003e` tag to include in the `\u003chead\u003e` section of the autogenerated `index.html` file. You can see an example of use in the web-frontend service [configuration file](https://github.com/layrjs/layr/blob/master/website/frontend/boostr.config.mjs) of the [Layr website](https://layrjs.com/).\n  - `scripts`: An array of objects specifying the attributes of some `\u003cscript\u003e` tags to include in the `\u003chead\u003e` section of the autogenerated `index.html` file. You can see an example of use in the web-frontend service [configuration file](https://github.com/layrjs/layr/blob/master/website/frontend/boostr.config.mjs) of the [Layr website](https://layrjs.com/).\n- `body`:\n  - `scripts`: An array of objects specifying the attributes of some `\u003cscript\u003e` tags to include in the `\u003cbody\u003e` section of the autogenerated `index.html` file.\n\n#### Web-Frontend AWS Configuration\n\nYou can customize the AWS configuration of a web frontend by specifying an object containing the following properties:\n\n- `region`: Specifies the AWS region (e.g., `'us-east-1'`) where the web frontend is deployed.\n- `profile`: Specifies an [AWS configuration profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) (e.g., `'my-company'`) used to get your AWS credentials. If not specified, your default AWS configuration profile is used.\n- `accessKeyId`: Allows you to specify your AWS Access Key ID when the `profile` property is not used, or you don't have a default [AWS configuration profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).\n- `secretAccessKey`: Allows you to specify your AWS Secret Access Key when the `profile` property is not used, or you don't have a default [AWS configuration profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).\n- `cloudFront`:\n  - `priceClass`: Specifies the Amazon CloudFront [price class](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/PriceClass.html) to use (default: `'PriceClass_100'`).\n\n### Backend Service\n\nA backend service is represented by a configuration file that specifies some properties related to the nature of a backend and some general properties, such as [environment](#environment-variables), [stages](#stages), and [dependsOn](#service-dependencies).\n\nHere's an example of a backend service configuration file:\n\n```js\n// backend/boostr.config.mjs\n\nexport default ({services}) =\u003e ({\n  type: 'backend',\n\n  dependsOn: 'database',\n\n  environment: {\n    FRONTEND_URL: services.frontend.url,\n    BACKEND_URL: services.backend.url,\n    DATABASE_URL: services.database.url\n  },\n\n  rootComponent: './src/index.ts',\n\n  stages: {\n    development: {\n      url: 'http://localhost:10743/',\n      platform: 'local'\n    },\n    staging: {\n      url: 'https://staging.backend.example.com/',\n      platform: 'aws',\n      aws: {\n        region: 'us-east-1',\n        lambda: {\n          memorySize: 1024\n        }\n      }\n    },\n    production: {\n      url: 'https://backend.example.com/',\n      platform: 'aws',\n      aws: {\n        region: 'us-east-1',\n        lambda: {\n          memorySize: 1024\n        }\n      }\n    }\n  }\n});\n```\n\nThe object returned by the exported function contains the following properties:\n\n- `type`: Specifies the type of service, which should always be `'backend'` in the case of a backend service.\n- `dependsOn`: Specifies that the `'backend'` service depends on the `'database'` service. See [\"Service Dependencies\"](#service-dependencies) for details.\n- `environment`: An object allowing you to define some [environment variables](#environment-variables) specific to the `'backend'` service. Note that `'FRONTEND_URL'`, `'BACKEND_URL'`, and `'DATABASE_URL'` are determined according to some service properties fetched from the `services` parameter of the configuration function. See [\"Service Property References\"](#service-property-references) for a detailed explanation.\n- `rootComponent`: Specifies the file's path implementing the root Layr component of your backend.\n- `stages`:\n  - `development`: An object allowing you to define some properties when the `'development'` [stage](#stages) is used.\n    - We define the `url` property so the frontend can access the backend locally (see [\"Local Development URLs\"](#local-development-urls) for details).\n    - We set the value of the `platform` property to `'local'` to indicate that Boostr should manage a local backend server.\n  - `staging` and `production`: An object allowing you to define some properties when the `'staging'` or `'production'` [stage](#stages) is used.\n    - We set the value of the `url` property to an URL where Boostr can deploy the backend (see [\"Deployment URLs\"](#deployment-urls) for details).\n    - We set the value of the `platform` property to `'aws'` to indicate that Boostr should use [AWS](https://aws.amazon.com/) as a deployment target.\n    - Optionally, we can specify an `aws` object to customize the AWS configuration (see [\"Backend AWS Configuration\"](#backend-aws-configuration) below for details).\n\n#### Backend AWS Configuration\n\nYou can customize the AWS configuration of a backend by specifying an object containing the following properties:\n\n- `region`: Specifies the AWS region (e.g., `'us-east-1'`) where the backend is deployed.\n- `profile`: Specifies an [AWS configuration profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) (e.g., `'my-company'`) used to get your AWS credentials. If not specified, your default AWS configuration profile is used.\n- `accessKeyId`: Allows you to specify your AWS Access Key ID when the `profile` property is not used, or you don't have a default [AWS configuration profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).\n- `secretAccessKey`: Allows you to specify your AWS Secret Access Key when the `profile` property is not used, or you don't have a default [AWS configuration profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).\n- `lambda`:\n  - `runtime`: Specifies the AWS Lambda [runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) to use (default: `'nodejs16.x'`).\n  - `executionRole`: Specifies the [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) used when the [Lambda function](https://aws.amazon.com/lambda/) is executed. If not specified, an automatically created role (named `'boostr-backend-lambda-role-v2'`) will be used, allowing [Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) management and [Lambda function](https://aws.amazon.com/lambda/) invocation.\n  - `memorySize`: Specifies the [amount of memory](https://docs.aws.amazon.com/lambda/latest/operatorguide/computing-power.html) (in megabytes) available to the [Lambda function](https://aws.amazon.com/lambda/) at runtime (default: `128`).\n  - `timeout`: Specifies the maximum time (in seconds) that the [Lambda function](https://aws.amazon.com/lambda/) can run (default: `10`).\n  - `reservedConcurrentExecutions`: Specifies the number of [concurrent executions](https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html) reserved for the [Lambda function](https://aws.amazon.com/lambda/) (default: `0`).\n\n### Database Service\n\nA database service is represented by a configuration file that specifies some properties related to the nature of a database and some general properties, such as [stages](#stages).\n\nHere's an example of a database service configuration file:\n\n```js\n// database/boostr.config.mjs\n\nexport default () =\u003e ({\n  type: 'database',\n\n  stages: {\n    development: {\n      url: 'mongodb://localhost:10744/dev',\n      platform: 'local'\n    }\n  }\n});\n```\n\nThe object returned by the exported function contains the following properties:\n\n- `type`: Specifies the type of service, which should always be `'database'` in the case of a database service.\n- `stages`:\n  - `development`: An object allowing you to define some properties when the `'development'` [stage](#stages) is used.\n    - We define the `url` property so the backend can access the database locally (see [\"Local Development URLs\"](#local-development-urls) for details).\n    - We set the value of the `platform` property to `'local'` to indicate that Boostr should manage a local database server.\n\nYou may wonder where are the URLs of the staging and production databases. Well, the problem is that we cannot put these URLs in `database/boostr.config.mjs` because they may contain sensitive information, such as access credentials.\n\nThankfully, we can add a [private configuration file](#private-configuration-files) to solve the issue:\n\n```js\n// database/boostr.config.private.mjs\n\nexport default () =\u003e ({\n  stages: {\n    staging: {\n      url: 'mongodb+srv://user:pass@clusterNane.mongodb.net/exampleStaging?retryWrites=true\u0026w=majority'\n    },\n    production: {\n      url: 'mongodb+srv://user:pass@clusterNane.mongodb.net/exampleProduction?retryWrites=true\u0026w=majority'\n    }\n  }\n});\n```\n\n### Environment Variables\n\n#### Defining Environment Variables\n\nUsing the `environment` object property, you can define environment variables in any configuration file.\n\nFor example, here's how you would define an `APPLICATION_NAME` environment variable in the root configuration:\n\n```js\n// boostr.config.mjs\n\nexport default () =\u003e ({\n  // ...\n\n  environment: {\n    APPLICATION_NAME: 'Layr App'\n  }\n\n  // ...\n});\n```\n\nAhd here's how you would define an `APPLICATION_DESCRIPTION` environment variable in a web-frontend service configuration:\n\n```js\n// frontend/boostr.config.mjs\n\nexport default () =\u003e ({\n  // ...\n\n  environment: {\n    APPLICATION_DESCRIPTION: 'A Layr app managed by Boostr.'\n  }\n\n  // ...\n});\n```\n\nAnd finally, here's how you would define a `DATABASE_URL` environment variable in a backend service configuration:\n\n```js\n// backend/boostr.config.mjs\n\nexport default ({services}) =\u003e ({\n  // ...\n\n  environment: {\n    DATABASE_URL: services.database.url\n  }\n\n  // ...\n});\n```\n\nNote that the value of `'DATABASE_URL'` is determined according to a `'database'` service property fetched from the `services` parameter of the configuration function. See [\"Service Property References\"](#service-property-references) for a detailed explanation.\n\n#### Global Environment Variables\n\nThe environment variables defined in the root configuration are global, and therefore, they are accessible from all the services of your app.\n\nSo, in the examples above, the web-frontend service has access to `APPLICATION_NAME` in addition to `APPLICATION_DESCRIPTION`, and the backend service has access to `APPLICATION_NAME` in addition to `DATABASE_URL`.\n\n#### Accessing Environment Variables\n\nYou can access environment variables from your app's code via the `process.env` object.\n\nFor example, here's how you would get the value of `APPLICATION_NAME` from your frontend code:\n\n```js\n// frontend/src/components/application.jsx\n\n// ...\n\nclass Application extends Base {\n  @view() static HeaderView() {\n    return \u003ch1\u003e{process.env.APPLICATION_NAME}\u003c/h1\u003e;\n  }\n}\n```\n\nAnd here's how you would get the value of `DATABASE_URL` from your backend code:\n\n```js\n// backend/src/index.ts\n\n// ...\n\nconst store = new MongoDBStore(process.env.DATABASE_URL);\n```\n\nEnvironment variables are also accessible when you run commands, such as [`test`](#boostr-service-test-options), [`eval`](#boostr-backend-service-eval-codetoeval-options), or [`repl`](#boostr-backend-service-repl-options).\n\nFor example, if you run the following command:\n\n```sh\nboostr backend eval process.env.APPLICATION_NAME\n```\n\nThe terminal should output something like this:\n\n```\n[database] MongoDB server started at mongodb://localhost:14128/\n[backend] Build succeeded (bundle size: 2.06MB)\n[backend] Evaluating code...\n[backend] Result:\n[backend] \"Layr App\"\n[database] MongoDB server stopped\n```\n\n### Stages\n\nGenerally, a Layr app managed by Boostr uses several stages, allowing you to define (or redefine) some configuration properties according to each stage.\n\nFor example, a typical app has the following stages:\n\n- `'development'`: A stage used when you run your app in development mode on your local machine.\n- `'staging'`: A stage used when you deploy your app to your staging hosting environment.\n- `'production'`: A stage used when you deploy your app to production.\n\n\u003e **Note**: You can define as many stages as you want and name them according to your preferences. However, if you use unconventional stage names, you won't be able to use a shorthand option, such as `--staging` or `--production`, to [select a stage](#selecting-stages).\n\n#### Defining Stages\n\nUsing the `stages` property, you can define stages in any configuration file.\n\nThe `stages` property should be an object composed of:\n\n- Keys that represent the name of your stages.\n- Values that allow you to define (or redefine) any configuration property according to each stage.\n\nHere's an example of a root configuration file using the `stages` property to change the value of the global `APPLICATION_NAME` environment variable for the `'development'` and `'staging'` stages:\n\n```js\n// boostr.config.mjs\n\nexport default () =\u003e ({\n  // ...\n\n  environment: {\n    APPLICATION_NAME: 'Layr App',\n    APPLICATION_DESCRIPTION: 'A Layr app managed by Boostr.'\n  },\n\n  stages: {\n    development: {\n      environment: {\n        APPLICATION_NAME: 'Layr App (development)'\n      }\n    },\n    staging: {\n      environment: {\n        APPLICATION_NAME: 'Layr App (staging)'\n      }\n    }\n  }\n});\n```\n\nNote that in the example above:\n\n- Since `APPLICATION_NAME` is not specified in a `'production`' stage, its value will be `'Layr App'` when the app is deployed to the `'production'` stage.\n- Since `APPLICATION_DESCRIPTION` is not specified in any stage, its value will always be `'A Layr app managed by Boostr.'`.\n\n#### Selecting Stages\n\nWhen you run a Boostr command, you can use the `--stage` option to select a stage.\n\nAlternatively, you can use one of the following shorthand options:\n\n- `--development`: A shorthand for `--stage=development`.\n- `--staging`: A shorthand for `--stage=staging`.\n- `--production`: A shorthand for `--stage=production`.\n\n\u003e **Note**: The default stage is `'development'`, which will be used if you don't explicitly select another stage.\n\n**Examples:**\n\n```sh\n# Starts the app while using the 'development' stage\nboostr start --stage=development\n\n# Since 'development' is the default stage, the following is equivalent\nboostr start\n```\n\n```sh\n# Deploys the app while using the 'production' stage\nboostr deploy --stage=production\n\n# Does the same thing by using the shorthand option\nboostr deploy --production\n```\n\n### Service Dependencies\n\nUsing the `dependsOn` property, you can specify dependencies between the services of your Layr app.\n\nSo, for example, you can specify that a web-frontend service depends on a backend service, which itself depends on a database service.\n\nWhen you start your app with the [`start`](#boostr-service-start-options) command, Boostr analyses the dependencies between your services and ensures that each dependency starts before each dependent.\n\nSo, in the example above, the services will start in the following order:\n\n1. Database service\n2. Backend service\n3. Web-frontend service\n\nThe same logic applies to other commands, such as the [`deploy`](#boostr-service-deploy-options) command.\n\nHere's an example showing how to specify a dependency between a web-frontend service and a backend service:\n\n```js\n// frontend/boostr.config.mjs\n\nexport default () =\u003e ({\n  type: 'web-frontend',\n\n  dependsOn: 'backend'\n\n  // ...\n});\n```\n\nAnd here's an example showing how to specify a dependency between a backend service and a database service:\n\n```js\n// backend/boostr.config.mjs\n\nexport default () =\u003e ({\n  type: 'backend',\n\n  dependsOn: 'database'\n\n  // ...\n});\n```\n\n### Service Property References\n\nUsing the `services` parameter of a configuration function, the services of your Layr app can reference each other.\n\nThis feature allows you to configure your app in a way that is 100% [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).\n\nFor example, let's take some configuration files:\n\n```js\n// boostr.config.mjs\n\nexport default () =\u003e ({\n  type: 'application',\n\n  services: {\n    frontend: './frontend',\n    backend: './backend'\n  }\n});\n```\n\n```js\n// frontend/boostr.config.mjs\n\nexport default ({services}) =\u003e ({\n  type: 'web-frontend',\n\n  environment: {\n    BACKEND_URL: services.backend.url\n  },\n\n  // ...\n\n  stages: {\n    development: {\n      url: 'http://localhost:10742/',\n      platform: 'local'\n    }\n  }\n});\n```\n\n```js\n// backend/boostr.config.mjs\n\nexport default ({services}) =\u003e ({\n  type: 'backend',\n\n  environment: {\n    FRONTEND_URL: services.frontend.url\n  },\n\n  // ...\n\n  stages: {\n    development: {\n      url: 'http://localhost:10743/',\n      platform: 'local'\n    }\n  }\n});\n```\n\nIn the web-frontend service, the value of the `'BACKEND_URL'` environment variable is fetched from the backend service (incidentally named `'backend'` in the root configuration), which is accessible thanks to the `services` parameter of the configuration function.\n\nYou can see the same mechanism used in the backend service. The value of the `'FRONTEND_URL'` environment variable is fetched from the web-frontend service (simply named `'frontend'` in the root configuration).\n\nNote that a service can even reference itself. For example, if, for some reason, you need a web-frontend service to be aware of its own URL through an environment variable, you can do so with the following configuration file:\n\n```js\n// frontend/boostr.config.mjs\n\nexport default ({services}) =\u003e ({\n  type: 'web-frontend',\n\n  environment: {\n    FRONTEND_URL: services.frontend.url\n  },\n\n  // ...\n\n  stages: {\n    development: {\n      url: 'http://localhost:10742/',\n      platform: 'local'\n    }\n  }\n});\n```\n\n### Local Development URLs\n\nA local development URL looks like `'http://localhost:10742/'` for a web-frontend or backend service and `'mongodb://localhost:10744/dev'` for a database service.\n\nWhen you initialize an app with the [`initialize`](#boostr-initialize-template-options) command, the TCP ports (e.g., `10742`) used for each service are randomly set. It ensures that you will never encounter port conflicts while working on several apps simultaneously.\n\n### Deployment URLs\n\nA deployment URL (e.g., `'https://example.com/'` or `'https://staging.example.com/'`) indicates where Boostr should deploy a service. Note that currently, the DNS associated with your base domain names (e.g., `'example.com'`) must be managed by [Amazon Route 53](https://aws.amazon.com/route53/).\n\n## Private Configuration Files\n\nMost apps use secrets that must remain private and never be included in your Git repositories (even if these repositories are private).\n\nYour app configuration files should be included in your Git repositories and, therefore, cannot contain any secrets.\n\nSo how could you configure secrets without exposing them?\n\nBoostr supports private configuration files that work like any configuration file but should be named `boostr.config.private.mjs` and stored next to your public configuration files named `boostr.config.mjs`.\n\nPrivate configuration files are automatically excluded from Git thanks to a line (e.g., `*.private.*`) in a `.gitignore` file at the root of your repositories.\n\nWhen Boostr evaluates your app's configuration, it reads both public and private configuration files and deeply merges them.\n\n\u003e **Note**: Private configurations precede public configurations, so a property found in a private configuration can override a property of the same name found in a public configuration.\n\n### Example\n\nLet's say your app implements an authentication mechanism using a [JWT library](https://jwt.io/libraries?language=Node.js) to sign and verify users' access tokens.\n\nJWT relies on a secret that should be accessible from your backend. So, in your backend directory, you could specify this secret in a private configuration file next to your public configuration file.\n\nHere's what your public configuration file would look like:\n\n```js\n// backend/boostr.config.mjs\n\nexport default () =\u003e ({\n  type: 'backend',\n\n  environment: {\n    EMAIL_ADDRESS: 'hello@example.com'\n  },\n\n  // ...\n\n  stages: {\n    development: {\n      // ...\n    },\n    production: {\n      // ...\n    }\n  }\n});\n```\n\nAnd here's what your private configuration file would look like:\n\n```js\n// backend/boostr.config.private.mjs\n\nexport default () =\u003e ({\n  stages: {\n    development: {\n      environment: {\n        JWT_SECRET: '26d9c27e799aba1b047ec16450a51418...'\n      }\n    },\n    production: {\n      environment: {\n        JWT_SECRET: '537df3079d44e066bf0195433863ec34...'\n      }\n    }\n  }\n});\n```\n\n## Inline Help\n\nYou can get some help from the Boostr CLI by using the `--help` option.\n\nGet some general help by running the following:\n\n```sh\nboostr --help\n```\n\nGet some help for a global command (e.g., `start`) by running the following:\n\n```sh\nboostr start --help\n```\n\nGet some help for a specific service (e.g., `'frontend'`) by running the following:\n\n```sh\nboostr frontend --help\n```\n\nGet some help for a command of a specific service (e.g., the `import` command of the `'database'` service) by running the following:\n\n```sh\nboostr database import --help\n```\n\n## Global Commands\n\nThe global commands are available for all services, including the root of your app, which is represented by a service of type `'application'`.\n\n### `boostr initialize \u003ctemplate\u003e [options]`\n\n_Alias: `boostr init`_\n\nInitializes your app within the current directory from the specified template.\n\nThe `\u003ctemplate\u003e` argument specifies the template to use, which should be a published npm package.\n\nCurrently, two templates are available:\n\n- `@boostr/web-app-js` for initializing a web app using JavaScript\n- `@boostr/web-app-ts` for initializing a web app using TypeScript\n\nWe will publish more templates in the future. For example, some [React Native](https://reactnative.dev/) or [Electron](https://www.electronjs.org/) app templates should soon be available.\n\nA template is simply an npm package. So, the community can publish any new template, and if needed, you can create some templates for your personal use.\n\n#### Options\n\nIn addition to the [global options](#global-options), the `initialize` command accepts the following option:\n\n- `--name`: Specifies the name of your app (defaults to the name of the current directory).\n\n#### Examples\n\n```sh\n# Creates a web app named `my-app` using TypeScript\nmkdir my-app\ncd my-app\nboostr initialize @boostr/web-app-ts\n```\n\nYou can check out the outcome of the above example in the [Boostr repository](./examples/web-app-ts/my-app).\n\n```sh\n# Creates a web app named `my-awesome-app` using JavaScript\nmkdir my-directory\ncd my-directory\nboostr init @boostr/web-app-js --name=my-awesome-app\n```\n\nYou can check out the outcome of the above example in the [Boostr repository](./examples/web-app-js/my-directory).\n\n### `boostr [\u003cservice\u003e] install [options]`\n\nInstalls all the npm dependencies used in your app (or a specified service).\n\nUnder the hood, this command runs `npm install`.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Examples\n\n```sh\n# Installs all the npm dependencies used in your app\nboostr install\n```\n\n```sh\n# Installs all the npm dependencies used in the 'frontend' service\nboostr frontend install\n```\n\n### `boostr [\u003cservice\u003e] update [options]`\n\nUpdates all the npm dependencies used in your app (or a specified service).\n\nUnder the hood, this command runs `npm update`.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Examples\n\n```sh\n# Updates all the npm dependencies used in your app (including Boostr itself)\nboostr update\n```\n\n```sh\n# Updates all the npm dependencies used in the 'backend' service\nboostr backend update\n```\n\n### `boostr [\u003cservice\u003e] check [options]`\n\nChecks the TypeScript code of your app (or a specified service).\n\nUnder the hood, this command runs `tsc --noEmit`.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Examples\n\n```sh\n# Checks the TypeScript code of your app\nboostr check\n```\n\n```sh\n# Checks the TypeScript code of the 'backend' service\nboostr backend check\n```\n\n### `boostr [\u003cservice\u003e] build [options]`\n\nBuilds runnable artifacts from the source code of your app (or a specified service).\n\n\u003e **Note**: This command is automatically executed when you run some other commands, such as [`start`](#boostr-service-start-options) or [`deploy`](#boostr-service-deploy-options). So, unless you want to check out the built runnable artifacts for debugging purposes, you should not have to use the `build` command explicitly.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Examples\n\n```sh\n# Builds runnable artifacts from the source code of your app\nboostr build\n```\n\n```sh\n# Builds runnable artifacts from the source code of the 'frontend' service\nboostr frontend build\n```\n\n```sh\n# Builds runnable artifacts from the source code of your app while using\n# the 'production' stage configuration\nboostr build --production\n```\n\n### `boostr [\u003cservice\u003e] test [options]`\n\nTests all the services of your app (or a specified service) in development mode.\n\nUnder the hood, this command runs `npm test`.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Examples\n\n```sh\n# Tests all the services of your app\nboostr test\n```\n\n```sh\n# Tests the 'backend' service\nboostr backend test\n```\n\n### `boostr [\u003cservice\u003e] start [options]`\n\nStarts your app (or a specified service) in development mode.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Examples\n\n```sh\n# Starts all the services of your app in development mode\nboostr start\n```\n\n```sh\n# Starts the 'backend' service (and the services it depends on)\n# in development mode\nboostr backend start\n```\n\n### `boostr [\u003cservice\u003e] migrate [options]`\n\nMigrates one or more databases used by your app.\n\n\u003e **Note**: Database migrations are limited to [MongoDB](https://www.mongodb.com/) for now.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Examples\n\n```sh\n# Migrates all the databases used by your app in the 'development' environment\nboostr migrate\n```\n\n```sh\n# Migrates all the databases used by your app in the 'staging' environment\nboostr migrate --staging\n```\n\n```sh\n# Migrates the 'customers' database in the 'development' environment\nboostr customers migrate\n```\n\n### `boostr [\u003cservice\u003e] deploy [options]`\n\nDeploys your app (or a specified service) to a specific [stage](#stages).\n\n#### Options\n\nIn addition to the [global options](#global-options), the `deploy` command accepts the following option:\n\n- `--skip`: Skips the specified service when deploying. Note that you can repeat this option several times to skip multiple services.\n\n#### Notes\n\n- Currently, only [AWS](https://aws.amazon.com/) is supported as a deployment target.\n- The DNS associated with your base domain name must be managed by [Amazon Route 53](https://aws.amazon.com/route53/).\n- The first deployment may take a while because several AWS services have to be set up, but subsequent deployments should be much faster.\n- Boostr manages the deployment of the web-frontend and backend services, but the database services are not. So, you will have to set up the databases by yourself on some cloud services, such as [MongoDB Atlas](https://www.mongodb.com/atlas/database) or [Amazon DocumentDB](https://aws.amazon.com/documentdb/).\n\n#### Examples\n\n```sh\n# Deploys all the services of your app to the 'staging' stage\nboostr deploy --stage=staging\n\n# Does the same thing by using the shorthand option\nboostr deploy --staging\n```\n\n```sh\n# Deploys all the services of your app to the 'production' stage\nboostr deploy --stage=production\n\n# Does the same thing by using the shorthand option\nboostr deploy --production\n```\n\n```sh\n# Deploys the 'backend' service (and the services it depends on)\n# to the 'production' stage\nboostr backend deploy --production\n```\n\n```sh\n# Deploys all the services of your app to the 'staging' stage while\n# skipping the 'legacyBackend' service\nboostr deploy --staging --skip=legacyBackend\n```\n\n### `boostr [\u003cservice\u003e] config [options]`\n\nDisplays the root (or a specified service) configuration.\n\n\u003e **Note**: The displayed configuration considers all the [property references](#service-property-references) and resolves them according to a specific [stage](#stages) (`'development'` by default).\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Examples\n\n```sh\n# Displays the root configuration for the 'development' environment\nboostr config\n```\n\n```sh\n# Displays the configuration of the 'frontend' service for the 'development' environment\nboostr frontend config\n```\n\n```sh\n# Displays the configuration of the 'backend' service for the 'production' environment\nboostr backend config --production\n```\n\n### `boostr [\u003cservice\u003e] exec [options] -- \u003ccommand\u003e ...`\n\nExecutes any shell command in the root directory of your app (or in the directory of a specified service).\n\n\u003e **Note**: The [environment variables](#environment-variables) specified in your configuration are accessible from the executed shell command.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Examples\n\n```sh\n# Executes `npx prettier --check .` in the root directory of your app\nboostr exec -- npx prettier --check .\n```\n\n```sh\n# Executes `npm install lodash` in the directory of the 'backend' service\nboostr backend exec -- npm install lodash\n```\n\n```sh\n# Executes `npm version patch --no-git-tag-version` in the directory of\n# the 'frontend' service\nboostr frontend exec -- npm version patch --no-git-tag-version\n```\n\n```sh\n# Executes `npm run myscript` in the directory of the 'backend' service\n# with the environment variables of the 'production' stage\nboostr backend exec --stage=production -- npm run myscript\n```\n\n## Web-Frontend Commands\n\nThe web-frontend commands are available for all services of type `'web-frontend'`.\n\n### `boostr \u003cweb-frontend-service\u003e freeze`\n\nFreezes all the files in your web-frontend service's `public` directory.\n\nFreezing a file means that the file is renamed to match the pattern `\u003cname\u003e-\u003chash\u003e.immutable.\u003cextension\u003e` where `\u003cname\u003e` is the original file name without its extension, `\u003chash\u003e` is a hash generated from the contents of the file, and `\u003cextension\u003e` is the original file extension.\n\nFor example, if you have a file named `favicon.png` in the `public` directory of your `'frontend'` service, running `boostr frontend freeze` will rename the `favicon.png` file to something like `favicon-3NjLR7w1Mu8UAIqq05vVG3.immutable.png`.\n\nWhen a browser loads a frozen file, it can permanently store it in its cache thanks to a `Cache-Control` header automatically added when your frontend is deployed.\n\n\u003e **Note**: It is not an issue to run the `freeze` command several times because the command is clever enough to ignore the files that have already been frozen.\n\n## Backend Commands\n\nThe backend commands are available for all services of type `'backend'`.\n\n### `boostr \u003cbackend-service\u003e eval \"\u003ccodeToEval\u003e\" [options]`\n\nEvaluates the specified JavaScript code with your backend service root component exposed globally and outputs the result in the terminal.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Example\n\nIf you run the following command with a web app that has just been initialized from the `@boostr/web-app-ts` template:\n\n```sh\nboostr backend eval \"Application.isHealthy()\"\n```\n\nThe terminal should output something like this:\n\n```\n[database] MongoDB server started at mongodb://localhost:10744/\n[backend] Build succeeded (bundle size: 2.06MB)\n[backend] Evaluating code...\n[backend] Result:\n[backend] true\n[database] MongoDB server stopped\n```\n\n### `boostr \u003cbackend-service\u003e repl [options]`\n\nStarts a Node.js [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) with your backend root component exposed globally.\n\n#### Options\n\nSee the [global options](#global-options).\n\n#### Example\n\nIf you run the following command with a web app that has just been initialized from the `@boostr/web-app-ts` template:\n\n```sh\nboostr backend repl\n```\n\nThen, you should be able to execute the following JavaScript code inside the REPL:\n\n```js\nawait Application.isHealthy();\n```\n\nAnd the REPL should output the following result:\n\n```\ntrue\n```\n\n## Global Options\n\nThe following options are available for most commands:\n\n- `--stage`: Selects a stage. See [\"Stages\"](#stages) for details.\n- `--development`: A shorthand for `--stage=development`.\n- `--staging`: A shorthand for `--stage=staging`.\n- `--production`: A shorthand for `--stage=production`.\n- `--help`, `-h`: Displays inline help. See [\"Inline Help\"](#inline-help) for details.\n- `--version`, `-v`: Displays the current Boostr version.\n\n## Contributing\n\nContributions are welcome.\n\nBefore contributing please read the [code of conduct](https://github.com/boostrjs/boostr/blob/master/CODE_OF_CONDUCT.md) and search the [issue tracker](https://github.com/boostrjs/boostr/issues) to find out if your issue has already been discussed before.\n\nTo contribute, [fork this repository](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo/), commit your changes, and [send a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboostrjs%2Fboostr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboostrjs%2Fboostr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboostrjs%2Fboostr/lists"}