diff --git a/.changeset/grumpy-yaks-travel.md b/.changeset/grumpy-yaks-travel.md new file mode 100644 index 0000000000..cb17d76d52 --- /dev/null +++ b/.changeset/grumpy-yaks-travel.md @@ -0,0 +1,5 @@ +--- +'@backstage/cli': patch +--- + +Minor update to the `index.html` template that updates the comment at the end to be more accurate. diff --git a/.changeset/tall-mugs-shake.md b/.changeset/tall-mugs-shake.md new file mode 100644 index 0000000000..e1f4104804 --- /dev/null +++ b/.changeset/tall-mugs-shake.md @@ -0,0 +1,21 @@ +--- +'@backstage/create-app': patch +--- + +The `build` script in the root `package.json` has been split into two separate scripts, `build:backend` and `build:all`. This is to more accurately reflect what is being built, to avoid confusion. + +If you want to build the project for a production deployment, you will want to use `build:backend`, as this builds both the frontend and backend package. If you are not using the `app-backend` plugin you will want to add your own `build:frontend` script, to which you can pass additional configuration parameters if needed. + +The `build:all` script is useful if you simply want to check that it is possible to build all packages in the project. This might be useful as a CI check, but is generally unnecessary. + +If you want to publish the packages in your repository you can add a `build:packages` script that calls `backstage-cli repo build`. This will skip the frontend and backend packages builds, as those are quite time consuming. + +To apply these changes to an existing project, make the following change to the root `package.json` file: + +```diff +- "build": "backstage-cli repo build --all", ++ "build:backend": "yarn workspace backend build", ++ "build:all": "backstage-cli repo build --all", +``` + +There are also a couple of places where documentation has been updated, see the [upgrade helper](https://backstage.github.io/upgrade-helper/?to=1.8.0) for a full list of changes. diff --git a/contrib/docs/tutorials/aws-deployment.md b/contrib/docs/tutorials/aws-deployment.md index 3a76da2ed3..a767d292bf 100644 --- a/contrib/docs/tutorials/aws-deployment.md +++ b/contrib/docs/tutorials/aws-deployment.md @@ -40,7 +40,7 @@ image](https://backstage.io/docs/getting-started/deployment-docker) documentation to build a new Backstage Docker image: ```shell -$ yarn build +$ yarn build:backend $ yarn build-image --tag backstage ``` diff --git a/cypress/README.md b/cypress/README.md index 15338fe371..4212af398c 100644 --- a/cypress/README.md +++ b/cypress/README.md @@ -24,7 +24,7 @@ necessary environment variables: ```sh yarn tsc -yarn build +yarn build:backend yarn workspace example-backend build-image docker run -p 7007:7007 example-backend ``` diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index 0b28e4d506..30276a97ab 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -34,8 +34,8 @@ more efficient caching of dependencies on the host, where a single change won't bust the entire cache. The required steps in the host build are to install dependencies with -`yarn install`, generate type definitions using `yarn tsc`, and build all -packages with `yarn build`. +`yarn install`, generate type definitions using `yarn tsc`, and build the backend +package with `yarn build:backend`. > NOTE: If you created your app prior to 2021-02-18, follow the > [migration step](https://github.com/backstage/backstage/releases/tag/release-2021-02-18) @@ -49,8 +49,8 @@ yarn install --frozen-lockfile # tsc outputs type definitions to dist-types/ in the repo root, which are then consumed by the build yarn tsc -# Build all packages and in the end bundle them all up into the packages/backend/dist folder. -yarn build +# Build the backend, which bundles it all up into the packages/backend/dist folder. +yarn build:backend ``` Once the host build is complete, we are ready to build our image. The following diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md index 9154eae4d1..1bf3d6bc7d 100644 --- a/docs/getting-started/contributors.md +++ b/docs/getting-started/contributors.md @@ -101,7 +101,8 @@ yarn workspace @backstage/plugin-api-docs start # Serve api-docs plugin only, al yarn tsc # Run typecheck, use --watch for watch mode yarn tsc:full # Run full type checking, for example without skipLibCheck, use in CI -yarn build # Build published versions of packages, depends on tsc +yarn build:backend # Build the backend package, depends on tsc +yarn build:all # Build published versions of packages, depends on tsc yarn lint # lint packages that have changed since later commit on origin/master yarn lint:all # lint all packages diff --git a/docs/getting-started/running-backstage-locally.md b/docs/getting-started/running-backstage-locally.md index 3e3e8b0727..a22156a87d 100644 --- a/docs/getting-started/running-backstage-locally.md +++ b/docs/getting-started/running-backstage-locally.md @@ -41,47 +41,38 @@ locally to use features like Software Templates and TechDocs. Please refer to the [installation instructions for Docker](https://docs.docker.com/engine/install/). -## Clone and Build +## Clone and Install To get up and running with a local Backstage to evaluate it, let's clone it off -of GitHub and run an initial build. +of GitHub and run an initial install. ```bash # Start from your local development folder git clone --depth 1 git@github.com:backstage/backstage.git cd backstage -# Fetch our dependencies and run an initial build +# Install our dependencies yarn install -yarn tsc -yarn build ``` Phew! Now you have a local repository that's ready to run and to add any open source contributions into. We are now going to launch two things: an example Backstage frontend app, and an -example Backstage backend that the frontend talks to. You are going to need two -terminal windows, both starting from the Backstage project root. - -In the first window, run +example Backstage backend that the frontend talks to. These can both be launched +through the following command: ```bash -# From your Backstage root directory -yarn --cwd packages/backend start +# From your Backstage root directory, launches both the frontend and backend +yarn dev ``` -That starts up a backend instance on port 7007. +If you prefer to run the frontend and backend separately, you can instead use `yarn start` +and `yarn start-backend` in two separate terminal windows. -In the other window, we will then launch the frontend. This command is run from -the project root, not inside the backend directory. - -```bash -yarn start -``` - -That starts up the frontend on port 3000, and should automatically open a -browser window showing it. +Which ever way you choose, you will now have a backend instance running on port 7007, +and the frontend running on port 3000. A browser window should also automatically open, +showing the frontend. ## Authentication diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md index 0af5fdb615..db84defd91 100644 --- a/docs/tutorials/package-role-migration.md +++ b/docs/tutorials/package-role-migration.md @@ -116,7 +116,7 @@ The way to execute this step of the migration is not as well defined as the prev - In places where the entire repo is being built, use `yarn backstage-cli repo build`, which also supports the `--since` flag. The migration here is a bit more nuanced as it depends on why you are building all packages. - If you are building all packages to **verify** that you are able to build them, you most likely want `backstage-cli repo build --all`. The `--all` flag signals that bundled packages like `packages/app` and `packages/backend` should be built as well. Pair this up with a `--since` flag in CI to avoid needing to build all packages. - If you are building all packages to **publish** them, then `backstage-cli repo build` is enough, as it builds all published packages. - - If you are building all packages to **deploy** them, you likely don't want to use the `repo` command at all, simply call `yarn build` in the packages you want to deploy instead. For example, if you are deploying the backend with a docker host build, it's enough to call `yarn build` inside `packages/backend`. + - If you are building all packages to **deploy** them, you likely don't want to use the `repo` command at all, simply call `yarn build` in the packages you want to deploy instead. For example, if you are deploying the backend with a docker host build, it's enough to call `yarn build` inside `packages/backend`. In a standard `@backstage/create-app` there is also a shorthand for building the backend from the root, `yarn build:backend`. ## FAQ diff --git a/package.json b/package.json index 3977bcc18f..d969db202c 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,8 @@ "dev": "concurrently \"yarn start\" \"yarn start-backend\"", "start": "yarn workspace example-app start", "start-backend": "yarn workspace example-backend start", - "build": "backstage-cli repo build --all", + "build:backend": "yarn workspace backend build", + "build:all": "backstage-cli repo build --all", "build:api-reports": "yarn build:api-reports:only --tsc", "build:api-reports:only": "ts-node -T -P scripts/tsconfig.json scripts/api-extractor.ts", "build:api-docs": "LANG=en_EN yarn build:api-reports --docs", diff --git a/packages/app/public/index.html b/packages/app/public/index.html index 863566e776..0710a0d69d 100644 --- a/packages/app/public/index.html +++ b/packages/app/public/index.html @@ -91,8 +91,8 @@ You can add webfonts, meta tags, or analytics to this file. The build step will place the bundled scripts into the tag. - To begin the development, run `npm start` or `yarn start`. - To create a production bundle, use `npm run build` or `yarn build`. + To begin the development, run `yarn start`. + To create a production bundle, use `yarn build`. --> diff --git a/packages/backend/Dockerfile b/packages/backend/Dockerfile index 60c6ffd27f..eca6ce82c2 100644 --- a/packages/backend/Dockerfile +++ b/packages/backend/Dockerfile @@ -5,7 +5,7 @@ # # yarn install # yarn tsc -# yarn build +# yarn build:backend # # Once the commands have been run, you can build the image using `yarn build-image` diff --git a/packages/backend/README.md b/packages/backend/README.md index c2145705e0..f4c115db65 100644 --- a/packages/backend/README.md +++ b/packages/backend/README.md @@ -14,8 +14,6 @@ To run the example backend, first go to the project root and run ```bash yarn install -yarn tsc -yarn build ``` You should only need to do this once. @@ -23,19 +21,11 @@ You should only need to do this once. After that, go to the `packages/backend` directory and run ```bash -AUTH_GOOGLE_CLIENT_ID=x AUTH_GOOGLE_CLIENT_SECRET=x \ -AUTH_GITHUB_CLIENT_ID=x AUTH_GITHUB_CLIENT_SECRET=x \ -AUTH_OAUTH2_CLIENT_ID=x AUTH_OAUTH2_CLIENT_SECRET=x \ -AUTH_OAUTH2_AUTH_URL=x AUTH_OAUTH2_TOKEN_URL=x \ -ROLLBAR_ACCOUNT_TOKEN=x \ -SENTRY_TOKEN=x \ -LOG_LEVEL=debug \ yarn start ``` -Substitute `x` for actual values, or leave them as -dummy values just to try out the backend without using the auth or sentry features. -You can also, instead of using dummy values for a huge number of environment variables, remove those config directly from app-config.yaml file located in the root folder. +If you want to override any configuration locally, for example adding any secrets, +you can do so in `app-config.local.yaml`. The backend starts up on port 7007 per default. diff --git a/packages/cli/templates/serve_index.html b/packages/cli/templates/serve_index.html index ff2426d3f3..08e48cb678 100644 --- a/packages/cli/templates/serve_index.html +++ b/packages/cli/templates/serve_index.html @@ -20,8 +20,8 @@ You can add webfonts, meta tags, or analytics to this file. The build step will place the bundled scripts into the tag. - To begin the development, run `npm start` or `yarn start`. - To create a production bundle, use `npm run build` or `yarn build`. + To begin the development, run `yarn start`. + To create a production bundle, use `yarn build`. --> diff --git a/packages/create-app/templates/default-app/package.json.hbs b/packages/create-app/templates/default-app/package.json.hbs index adcd3a5774..070cb871bc 100644 --- a/packages/create-app/templates/default-app/package.json.hbs +++ b/packages/create-app/templates/default-app/package.json.hbs @@ -9,7 +9,8 @@ "dev": "concurrently \"yarn start\" \"yarn start-backend\"", "start": "yarn workspace app start", "start-backend": "yarn workspace backend start", - "build": "backstage-cli repo build --all", + "build:backend": "yarn workspace backend build", + "build:all": "backstage-cli repo build --all", "build-image": "yarn workspace backend build-image", "tsc": "tsc", "tsc:full": "tsc --skipLibCheck false --incremental false", diff --git a/packages/create-app/templates/default-app/packages/app/public/index.html b/packages/create-app/templates/default-app/packages/app/public/index.html index b548d8fb70..c6083b3dd2 100644 --- a/packages/create-app/templates/default-app/packages/app/public/index.html +++ b/packages/create-app/templates/default-app/packages/app/public/index.html @@ -54,8 +54,8 @@ You can add webfonts, meta tags, or analytics to this file. The build step will place the bundled scripts into the tag. - To begin the development, run `npm start` or `yarn start`. - To create a production bundle, use `npm run build` or `yarn build`. + To begin the development, run `yarn start`. + To create a production bundle, use `yarn build`. --> diff --git a/packages/create-app/templates/default-app/packages/backend/Dockerfile b/packages/create-app/templates/default-app/packages/backend/Dockerfile index f0be3ac1d3..51f7124db4 100644 --- a/packages/create-app/templates/default-app/packages/backend/Dockerfile +++ b/packages/create-app/templates/default-app/packages/backend/Dockerfile @@ -5,7 +5,7 @@ # # yarn install # yarn tsc -# yarn build +# yarn build:backend # # Once the commands have been run, you can build the image using `yarn build-image` diff --git a/packages/create-app/templates/default-app/packages/backend/README.md b/packages/create-app/templates/default-app/packages/backend/README.md index 02426ef9b3..aa042db030 100644 --- a/packages/create-app/templates/default-app/packages/backend/README.md +++ b/packages/create-app/templates/default-app/packages/backend/README.md @@ -16,8 +16,6 @@ To run the example backend, first go to the project root and run ```bash yarn install -yarn tsc -yarn build ``` You should only need to do this once. @@ -25,16 +23,11 @@ You should only need to do this once. After that, go to the `packages/backend` directory and run ```bash -AUTH_GOOGLE_CLIENT_ID=x AUTH_GOOGLE_CLIENT_SECRET=x \ -AUTH_GITHUB_CLIENT_ID=x AUTH_GITHUB_CLIENT_SECRET=x \ -AUTH_OAUTH2_CLIENT_ID=x AUTH_OAUTH2_CLIENT_SECRET=x \ -AUTH_OAUTH2_AUTH_URL=x AUTH_OAUTH2_TOKEN_URL=x \ -LOG_LEVEL=debug \ yarn start ``` -Substitute `x` for actual values, or leave them as dummy values just to try out -the backend without using the auth or sentry features. +If you want to override any configuration locally, for example adding any secrets, +you can do so in `app-config.local.yaml`. The backend starts up on port 7007 per default. diff --git a/packages/e2e-test/README.md b/packages/e2e-test/README.md index 139213c0c1..f3692de2a7 100644 --- a/packages/e2e-test/README.md +++ b/packages/e2e-test/README.md @@ -11,7 +11,7 @@ All packages need to be installed and built before running the test. In a fresh ```sh yarn install yarn tsc -yarn build +yarn build:all ``` Once those tasks have completed, you can now run the test using `yarn e2e-test run`. diff --git a/packages/e2e-test/src/commands/run.ts b/packages/e2e-test/src/commands/run.ts index f32d577cd4..fe4d87bea4 100644 --- a/packages/e2e-test/src/commands/run.ts +++ b/packages/e2e-test/src/commands/run.ts @@ -275,7 +275,7 @@ async function createApp( for (const cmd of [ 'install', 'tsc:full', - 'build', + 'build:all', 'lint:all', 'prettier:check', 'test:all', diff --git a/packages/techdocs-cli-embedded-app/public/index.html b/packages/techdocs-cli-embedded-app/public/index.html index b548d8fb70..c6083b3dd2 100644 --- a/packages/techdocs-cli-embedded-app/public/index.html +++ b/packages/techdocs-cli-embedded-app/public/index.html @@ -54,8 +54,8 @@ You can add webfonts, meta tags, or analytics to this file. The build step will place the bundled scripts into the tag. - To begin the development, run `npm start` or `yarn start`. - To create a production bundle, use `npm run build` or `yarn build`. + To begin the development, run `yarn start`. + To create a production bundle, use `yarn build`. -->