diff --git a/README.md b/README.md index d2a0bbd3a9..fe73c1257c 100644 --- a/README.md +++ b/README.md @@ -62,11 +62,12 @@ To run a Backstage app, you will need to have the following installed: - [NodeJS](https://nodejs.org/en/download/) - Active LTS Release, currently v12 - [yarn](https://classic.yarnpkg.com/en/docs/install) -After cloning this repo, open a terminal window and start the web app using the following commands from the project root: +After cloning this repo, open a terminal window and start the example app using the following commands from the project root: ```bash -yarn install -yarn start +yarn install # Install dependencies + +yarn start # Start dev server, use --check to enable linting and type-checks ``` The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal. diff --git a/docs/getting-started/create-a-plugin.md b/docs/getting-started/create-a-plugin.md index 7b8a7cf29b..64412c8b89 100644 --- a/docs/getting-started/create-a-plugin.md +++ b/docs/getting-started/create-a-plugin.md @@ -24,6 +24,15 @@ plugin directly by navigating to `http://localhost:3000/my-plugin`._ my plugin

+You can also serve the plugin in isolation by running `yarn start` in the plugin directory. Or by using the yarn workspace command, for example: + +```bash +yarn workspace @backstage/plugin-welcome start # Also supports --check +``` + +This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. +It is only meant for local development, and the setup for it can be found inside the plugin's `dev/` directory. + [Next Step - Structure of a plugin](structure-of-a-plugin.md) [Back to Getting Started](README.md) diff --git a/docs/getting-started/development-environment.md b/docs/getting-started/development-environment.md index 7f6e2bcb44..4dd2f7c9c7 100644 --- a/docs/getting-started/development-environment.md +++ b/docs/getting-started/development-environment.md @@ -1,5 +1,7 @@ # Development Environment +## Serving the Example App + Open a terminal window and start the web app using the following commands from the project root: ```bash @@ -21,6 +23,40 @@ You can now view example-app in the browser. On Your Network: http://192.168.1.224:8080 ``` +## Editor + +The Backstage development environment does not require any specific editor, but it is intended to be used with one that has built-in linting and type-checking. The development server does not include any checks by default, but they can be enabled using the `--check` flag. Note that using the flag may consume more system resources and slow things down. + +## Package Scripts + +There are many commands to be found in the root [package.json](package.json), here are some useful ones: + +```python +yarn start # Start serving the example app, use --check to include type checks and linting + +yarn storybook # Start local storybook, useful for working on components in @backstage/core + +yarn workspace @backstage/plugin-welcome start # Serve welcome plugin only, also supports --check + +yarn tsc # Run typecheck, use --watch for watch mode + +yarn build # 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 + +yarn test # test packages that have changed since later commit on origin/master +yarn test:all # test all packages + +yarn clean # Remove all output folders and @backstage/cli cache + +yarn bundle # Build a production bundle of the example app + +yarn diff # Make sure all plugins are up to date with the latest plugin template + +yarn create-plugin # Create a new plugin +``` + ### (Optional)Try on Docker Run the following commands if you have Docker environment