From c47b8583bd16c7717890320ee7ce22d2f768817f Mon Sep 17 00:00:00 2001 From: David Dal Busco Date: Sat, 24 Feb 2024 09:46:32 +0100 Subject: [PATCH] docs: juno.config.ts|js|json (#94) * docs: juno.config.ts|js|json Signed-off-by: David Dal Busco * docs: no mode in example Signed-off-by: David Dal Busco --------- Signed-off-by: David Dal Busco --- docs/build/hosting.md | 4 +- docs/miscellaneous/cli.md | 73 +++++----- docs/miscellaneous/configuration.md | 135 ++++++++++++++++++ docs/miscellaneous/controllers.md | 2 +- docs/miscellaneous/local-development.md | 16 +-- docs/miscellaneous/memory.md | 2 +- docs/miscellaneous/monitoring.md | 2 +- docs/miscellaneous/plugins.md | 4 +- .../sdk-usage-in-anodejs-context.md | 2 +- 9 files changed, 184 insertions(+), 56 deletions(-) create mode 100644 docs/miscellaneous/configuration.md diff --git a/docs/build/hosting.md b/docs/build/hosting.md index 9face4ba..05a0c231 100644 --- a/docs/build/hosting.md +++ b/docs/build/hosting.md @@ -99,11 +99,11 @@ You can configure customized hosting behavior for requests to your site. #### Where do you define your Hosting configuration? -You define your Hosting configuration in your `juno.json` file. The CLI automatically creates the file at the root of your project directory when you run the [juno init](../miscellaneous/cli.md#init) or [juno deploy](../miscellaneous/cli.md#deploy) command for the first time. +You define your Hosting configuration in your Juno configuration file. The CLI automatically creates the file at the root of your project directory when you run the [juno init](../miscellaneous/cli.md#init) or [juno deploy](../miscellaneous/cli.md#deploy) command for the first time. #### How do you apply your changes? -To apply any changes you make to your configuration in `juno.json` to your satellite, simply use the [juno config](../miscellaneous/cli.md#config) command with the CLI. +To apply any changes you make in your configuration to your satellite, execute the [juno config](../miscellaneous/cli.md#config) command with the CLI. ### Source diff --git a/docs/miscellaneous/cli.md b/docs/miscellaneous/cli.md index 621d25e4..d4289a2c 100644 --- a/docs/miscellaneous/cli.md +++ b/docs/miscellaneous/cli.md @@ -6,6 +6,8 @@ sidebar_position: 1 The Juno CLI (GitHub: https://github.com/junobuild) provides a variety of tools for managing and deploying [satellite]. +--- + ## Installation 1. Install Node.js (version LTS or above) from https://nodejs.org/en/download/. You can use nvm (https://github.com/nvm-sh/nvm) to manage multiple Node.js versions on a single machine. @@ -16,9 +18,11 @@ The Juno CLI (GitHub: https://github.com/junobuild) provides a variety of tools npm i -g @junobuild/cli ``` +--- + ## Login -The CLI requires authentication to make changes, such as deploying an application, upgrading a [satellite] or mission control, etc. +The CLI requires authentication to make changes, such as deploying an application, upgrading a satellite or mission control, etc. The authentication process requires a browser: @@ -42,17 +46,19 @@ If you've previously authenticated your terminal and decide to log in again, the ::: -### How it works? +### How does it work? -A new [principal] is generated on your local machine and added as a [controller] of the selected satellites and/or mission control. This principal is then used to authenticate any CLI calls made from your terminal to your satellites and mission controls. +A new [principal] is generated on your local machine and added as a [controller] of the selected segments. This principal is then used to authenticate any CLI calls made from your terminal to your satellites and mission controls. The key is saved in the OS-specific user's variables path. -- macOS: `~/Library/Preferences/juno-nodejs` -- Windows: `%APPDATA%\juno-nodejs\Config` (for example, `C:\Users\USERNAME\AppData\Roaming\juno-nodejs\Config`) -- Linux: `~/.config/juno-nodejs` (or `$XDG_CONFIG_HOME/juno-nodejs`) +| OS | Path | +| ------- | ---------------------------------------------------------------------------------------------------- | +| Mac | `~/Library/Preferences/juno-nodejs` | +| Windows | `%APPDATA%\juno-nodejs\Config` (for example, `C:\Users\USERNAME\AppData\Roaming\juno-nodejs\Config`) | +| Linux | `~/.config/juno-nodejs` (or `$XDG_CONFIG_HOME/juno-nodejs`) | -To get the paths for storing data the CLI is using the library [env-paths](https://github.com/sindresorhus/env-paths#pathsconfig). +--- ## Logout @@ -62,38 +68,31 @@ To remove the authorization of your local machine: juno logout ``` -:::note +:::caution -This currently does not remove the controllers from satellites and/or mission control. It only logs out your local machine and removes the locally saved key (principal). +This currently does not remove the controllers from satellites and/or mission control and/or orbiter. It only logs out your local machine and removes the locally saved key (principal). ::: -## Init +--- -The `juno init` command creates a `juno.json` configuration file in the root of your project directory. +## Init -This file is necessary to deploy your app with the CLI as it specifies which files from your project directory will be deployed to which satellite. +The `juno init` command creates a `juno.config` file in the root directory of your project. -The satellite ID and path can be configured or edited manually through juno init. +You will be prompted to select your preferred format: TypeScript, JavaScript, or JSON. -:::note +:::tip -Running `juno init` will overwrite the `juno.json` configuration file. +We recommend using the first two options because they can leverage your IDE's IntelliSense with type hints. ::: -The following is an example `juno.json`: +This file is necessary for deploying, configuring, or running any other CLI commands for your app. -```json -{ - "satellite": { - "satelliteId": "qsgjb-riaaa-aaaaa-aaaga-cai", - "source": "dist" - } -} -``` +Read more about the [configuration](./configuration.md). -You can [configure your Hosting behavior](../build/hosting.md#configure-hosting-behavior) by specifying various options within that file. +--- ## Deploy @@ -109,6 +108,8 @@ This command uploads each file separately and computes and uploads the correspon ::: +--- + ## Config To apply any changes to your [storage](../build/storage.md) configuration, run the following command from your project directory: @@ -117,6 +118,8 @@ To apply any changes to your [storage](../build/storage.md) configuration, run t juno config ``` +--- + ## Clear To clear the on-chain assets of the app, run the following command: @@ -137,32 +140,22 @@ If you have compressed (gzip and brotli) your bundle and assets after deploying ::: +--- + ## Upgrade -If the smart contracts' code of your mission control or satellites become outdated, you can upgrade them. +If the smart contracts' code of your mission control, satellites or orbiters become outdated, you can upgrade them. Running the following command from the project directory upgrade your satellite (default option): ```bash -juno upgrade -``` - -By adding a suffix `-m` or `--mission-control`, you can upgrade your mission control: - -```bash -juno upgrade -m -``` - -Likewise, by using the suffix `-o` or `--orbiter`, you can upgrade your orbiter for the analytics: - -```bash -juno upgrade -o +juno upgrade --target s|m|o ``` :::caution - We recommend that you stay current with the Juno releases, as some features may not perform correctly in the [console](../terminology.md#console) if your smart contracts are outdated. -- Upgrading is as complex as migrating storage and requires a stable internet connection for a successful process. +- Upgrading requires a stable internet connection for a successful process. ::: diff --git a/docs/miscellaneous/configuration.md b/docs/miscellaneous/configuration.md new file mode 100644 index 00000000..e7bae2c7 --- /dev/null +++ b/docs/miscellaneous/configuration.md @@ -0,0 +1,135 @@ +--- +sidebar_position: 3 +--- + +# Configuration + +When running `juno` from the command line, it will automatically attempt to locate a config file named `juno.config.ts` or `juno.config.js` or `juno.config.json` within your project's root directory. + +A basic config file looks like this: + +```typescript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + satelliteId: "aaaaa-bbbbb-ccccc-ddddd-cai", + source: "build" + } +}); +``` + +--- + +## Config Intellisense + +To enable intellisense in your IDE for TypeScript or JavaScript configurations, you will need to install the necessary types: + +```bash +npm install @junobuild/config --save-dev +``` + +Afterwards, you can leverage your IDE's intellisense with jsdoc type hints: + +```javascript title="juno.config.js" +/** @type {import('@junobuild/config').JunoConfig} */ +export default { + // ... +}; +``` + +Alternatively, you can use the `defineConfig` helper which should provide intellisense without the need for jsdoc annotations: + +```javascript title="juno.config.js" +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + // ... +}); +``` + +--- + +## Conditional Config + +If the config needs to conditionally determine options based the `mode` being used, it can export a function instead: + +```javascript title="juno.config.js" +import { defineConfig } from "@junobuild/config"; + +export default defineConfig(({ mode }) => ({ + satellite: { + satelliteId: "aaaaa-bbbbb-ccccc-ddddd-cai", + source: "dist", + ...(mode === "production" && { iframe: true }) + } +})); +``` + +--- + +## Modes + +By default, the CLI runs command for the `production` mode. + +This means when running a `juno` command in your terminal, it will pass the mode `production` to read your configuration. + +You can overwrite the default mode used for a command by passing the `--mode` option flag. For example, if you want to deploy your app for a `staging` mode: + +```bash +juno deploy --mode staging +``` + +--- + +## Environments - Multiple satellites + +You may wish to deploy or operate a similar project across various environments. For instance, deploying the same application on multiple satellites can be accomplished by utilizing [modes](#modes). + +To accommodate different satellite IDs, you can use a [conditional config](#conditional-config): + +```javascript title="juno.config.js" +import { defineConfig } from "@junobuild/config"; + +export default defineConfig(({ mode }) => ({ + satellite: { + satelliteId: + mode === "staging" + ? "11111-22222-33333-44444-cai" + : "aaaaa-bbbbb-ccccc-ddddd-cai", + source: "dist" + } +})); +``` + +Or explicitly list the IDs: + +```javascript title="juno.config.js" +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + satelliteIds: { + staging: "11111-22222-33333-44444-cai", + production: "aaaaa-bbbbb-ccccc-ddddd-cai" + }, + source: "dist" + } +}); +``` + +The latter method is also compatible with JSON configuration: + +```json title="juno.config.json" +{ + "satellite": { + "satelliteIds": { + "staging": "11111-22222-33333-44444-cai", + "production": "aaaaa-bbbbb-ccccc-ddddd-cai" + }, + "source": "dist" + } +} +``` + +Note that defining a `satelliteId` or at least a `production` entry in `satelliteIds` is mandatory. diff --git a/docs/miscellaneous/controllers.md b/docs/miscellaneous/controllers.md index 5f7ab166..f3f61918 100644 --- a/docs/miscellaneous/controllers.md +++ b/docs/miscellaneous/controllers.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 9 --- # Controllers diff --git a/docs/miscellaneous/local-development.md b/docs/miscellaneous/local-development.md index 62ab4e55..6ca148e8 100644 --- a/docs/miscellaneous/local-development.md +++ b/docs/miscellaneous/local-development.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 --- # Local development @@ -38,16 +38,16 @@ services: - 5987:5987 volumes: - my_dapp:/juno/.juno - - ./juno.dev.json:/juno/juno.dev.json + - ./juno.dev.config.json:/juno/juno.dev.config.json - ./target/deploy:/juno/target/deploy/ volumes: my_dapp: ``` -In addition, create a file named `juno.dev.json` next to your Docker Compose file and populate it with the required fields. +In addition, create a file named `juno.dev.config.json` next to your Docker Compose file and populate it with the required fields. -```json title="juno.dev.json" +```json title="juno.dev.config.json" { "satellite": { "collections": {} @@ -107,7 +107,7 @@ services: - 5987:5987 volumes: - hello_world:/juno/.juno # <-------- hello_world modified here - - ./juno.dev.json:/juno/juno.dev.json + - ./juno.dev.config.json:/juno/juno.dev.config.json - ./target/deploy:/juno/target/deploy/ volumes: @@ -118,7 +118,7 @@ volumes: ## Configuration -The behavior of the Satellite running in the Docker container can be configured with the help of a local configuration file commonly named `juno.dev.json`. +The behavior of the Satellite running in the Docker container can be configured with the help of a local configuration file commonly named `juno.dev.config.json`. This configuration file enables you to define the collections of the Datastore and Storage that run locally, but it also allows for defining additional controllers for your satellite. @@ -161,7 +161,7 @@ export interface JunoDevConfig { If, for example, we want to configure a "metadata" collection in the Datastore, a "content" collection in the Storage, and provide an additional controller, we could use the following configuration: -```json title="juno.dev.json" +```json title="juno.dev.config.json" { "satellite": { "collections": { @@ -204,7 +204,7 @@ services: - 5987:5987 volumes: - my_dapp:/juno/.juno - - /your/custom/path/your_config_file.json:/juno/juno.dev.json # <-------- Modify location and file name of the left hand part + - /your/custom/path/your_config_file.json:/juno/juno.dev.config.json # <-------- Modify location and file name of the left hand part volumes: my_dapp: diff --git a/docs/miscellaneous/memory.md b/docs/miscellaneous/memory.md index c2ddfb90..446b3976 100644 --- a/docs/miscellaneous/memory.md +++ b/docs/miscellaneous/memory.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # Memory diff --git a/docs/miscellaneous/monitoring.md b/docs/miscellaneous/monitoring.md index 165867d8..8c737853 100644 --- a/docs/miscellaneous/monitoring.md +++ b/docs/miscellaneous/monitoring.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Monitoring diff --git a/docs/miscellaneous/plugins.md b/docs/miscellaneous/plugins.md index bebddba9..563d5b2a 100644 --- a/docs/miscellaneous/plugins.md +++ b/docs/miscellaneous/plugins.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- # Plugins @@ -8,7 +8,7 @@ Juno provides various plugins to simplify your development workflow. We also war ## Vite Plugin -If you are developing your app using Vite, this plugin automatically loads the Satellite ID from your project's `juno.json`. If you are using analytics, it also loads the Orbiter ID too. +If you are developing your app using Vite, this plugin automatically loads the Satellite ID from your project's configuration file. If you are using analytics, it also loads the Orbiter ID too. These values allow you to instantiate Juno in your code without the need to manually define environment variables. diff --git a/docs/miscellaneous/sdk-usage-in-anodejs-context.md b/docs/miscellaneous/sdk-usage-in-anodejs-context.md index 56e2f20d..4305589a 100644 --- a/docs/miscellaneous/sdk-usage-in-anodejs-context.md +++ b/docs/miscellaneous/sdk-usage-in-anodejs-context.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 --- # SDK usage in a NodeJS context