Merge pull request #285 from jovotech/v4/improvement/docs

📝 Improve docs

.github/workflows/action.yml

@@ -18,5 +18,5 @@ jobs:
  - run: npm install
  - run: npm run bootstrap
  - run: npm run eslint
- - run: npm run tsc
+ - run: npm run build
  - run: npm run test

cli/package.json

@@ -14,7 +14,8 @@
  "jovo": "./bin/run"
  },
  "scripts": {
- "tsc": "tsc",
+ "build": "tsc",
+ "build:watch": "tsc --watch",
  "eslint": "eslint src --ext .ts --fix",
  "test": "jest",
  "link": "node bin/link",

commands/command-build/package.json

@@ -7,7 +7,8 @@
  "types": "dist/index.d.ts",
  "license": "Apache-2.0",
  "scripts": {
- "tsc": "tsc",
+ "build": "tsc",
+ "build:watch": "tsc --watch",
  "eslint": "eslint src --ext .ts --fix",
  "test": "jest"
  },

commands/command-deploy/package.json

@@ -7,7 +7,8 @@
  "types": "dist/index.d.ts",
  "license": "Apache-2.0",
  "scripts": {
- "tsc": "tsc",
+ "build": "tsc",
+ "build:watch": "tsc --watch",
  "eslint": "eslint src --ext .ts --fix",
  "test": "jest"
  },

commands/command-get/package.json

@@ -7,7 +7,8 @@
  "types": "dist/index.d.ts",
  "license": "Apache-2.0",
  "scripts": {
- "tsc": "tsc",
+ "build": "tsc",
+ "build:watch": "tsc --watch",
  "eslint": "eslint src --ext .ts --fix",
  "test": "jest"
  },

commands/command-new/package.json

@@ -7,7 +7,8 @@
  "types": "dist/index.d.ts",
  "license": "Apache-2.0",
  "scripts": {
- "tsc": "tsc",
+ "build": "tsc",
+ "build:watch": "tsc --watch",
  "eslint": "eslint src --ext .ts --fix",
  "test": "jest"
  },

commands/command-run/package.json

@@ -7,14 +7,14 @@
  "types": "dist/index.d.ts",
  "license": "Apache-2.0",
  "scripts": {
- "tsc": "tsc",
+ "build": "tsc",
+ "build:watch": "tsc --watch",
  "eslint": "eslint src --ext .ts --fix",
  "test": "jest"
  },
  "dependencies": {
  "@jovotech/cli-core": "^4.0.1",
  "@oclif/parser": "^3.8.5",
- "boxen": "^5.0.0",
  "global-dirs": "^3.0.0",
  "lodash.merge": "^4.6.2",
  "nodemon": "^2.0.7",

commands/command-run/src/utilities.ts

@@ -1,27 +1,4 @@
-import {
- execAsync,
- ExecResponse,
- JovoCliError,
- JovoUserConfigFile,
- Package,
- UserConfig,
-} from '@jovotech/cli-core';
-
-/**
- * Compile TypeScript code of Jovo project to JavaScript.
- * @param sourceFolder - Source folder.
- */
-export async function compileTypeScriptProject(sourceFolder: string): Promise<void> {
- try {
- await execAsync('npm run tsc', { cwd: sourceFolder });
- } catch (error) {
- throw new JovoCliError({
- message: (error as ExecResponse).stderr!,
- module: 'RunCommand',
- details: (error as ExecResponse).stdout,
- });
- }
-}
+import { JovoUserConfigFile, Package, UserConfig } from '@jovotech/cli-core';
 
 /**
  * Checks whether to display an update message for out-of-date packages or not.

commands/command-update/package.json

@@ -1,13 +1,14 @@
 {
  "name": "@jovotech/cli-command-update",
- "description": "Jovo CLI Plugin for updating dependencies",
+ "description": "Jovo CLI Plugin for updating Jovo packages",
  "version": "4.0.0-alpha.0",
  "author": "jovotech",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "license": "Apache-2.0",
  "scripts": {
- "tsc": "tsc",
+ "build": "tsc",
+ "build:watch": "tsc --watch",
  "eslint": "eslint src --ext .ts --fix",
  "test": "jest"
  },

core/package.json

@@ -8,7 +8,8 @@
  "license": "Apache-2.0",
  "scripts": {
  "test": "jest",
- "tsc": "tsc",
+ "build": "tsc",
+ "build:watch": "tsc --watch",
  "eslint": "eslint src test --ext .ts --fix"
  },
  "dependencies": {

docs/README.md

@@ -20,7 +20,7 @@ With the Jovo CLI, you can do many things, including:
 
 Learn how to install the Jovo CLI in the [installation](#installation) section. In the [configuration](#configuration) section, we'll take a look at configurations and plugins that can be added to the CLI.
 
-After that, we'll take a look at all [CLI commands](#commands) and ways to [extend the Jovo CLI](#extend-the-jovo-cli).
+After that, we'll take a look at all [CLI commands](#commands) and ways to [extend the Jovo CLI](#extend-the-jovo-cli). For bugfixes, take a look at the [local setup](#local-setup) section.
 
 ## Installation
 
@@ -62,7 +62,7 @@ Learn more about the Jovo CLI commands:
 - [`new`](https://www.jovo.tech/docs/new-command): Create a new Jovo project
 - [`run`](https://www.jovo.tech/docs/run-command): Start the local development server
 - [`build`](https://www.jovo.tech/docs/build-command): Create platform-specific project files
-- [`deploy`](https://www.jovo.tech/docs/deplooy-command): Deploy to various platforms and services
+- [`deploy`](https://www.jovo.tech/docs/deploy-command): Deploy to various platforms and services
 - [`get`](https://www.jovo.tech/docs/get-command): Sync your local files with platform files
 - [`update](https://www.jovo.tech/docs/update-command): Update Jovo packages in your project
 
@@ -82,3 +82,42 @@ There are two ways how you can extend the Jovo CLI:
 
 - [CLI hooks](https://www.jovo.tech/docs/project-config#hooks): Hook into existing CLI commands. For example, call an API and retrieve data as part of the `build` command.
 - [CLI plugins](https://www.jovo.tech/docs/cli-plugins): Create your own plugins that could hook into commands, or even create commands on their own.
+
+### Local Setup
+
+If you want to extend the Jovo CLI functionality, it should be sufficient to follow the steps mentioned above. However, if you encounter any issues or want to dig deeper into core functionality, it might be useful to set up the CLI for local development.
+
+To get started, clone the CLI repository to your workspace. Here is a list of options:
+
+```sh
+# HTTPS
+$ git clone https://github.com/jovotech/jovo-cli.git
+
+# SSH
+$ git clone git@github.com:jovotech/jovo-cli.git
+
+# GitHub ClI
+$ gh repo clone jovotech/jovo-cli
+```
+
+Now, go to the created project and run the local setup script:
+
+```sh
+# Change directory to the created project
+$ cd jovo-cli
+
+# Run the local setup script
+$ npm run setup:dev
+```
+
+This will install all necessary dependencies and link the local binary to `jovodev`. This allows you to apply and test changes in the code directly by recompiling the corresponding module and running `jovodev`.
+
+```sh
+$ jovodev
+```
+
+For example, if you need to make some changes to the `build:platform` command, you need to go into `jovo-cli/commands/command-build`, adjust the code to your needs and recompile it using `npm run build`, or `npm run build:watch` if you want to recompile on code changes automatically (similar to `nodemon`). When running the command using `jovodev`, you should see your changes implemented:
+
+```sh
+$ jovodev build:platform
+```

docs/cli-plugins.md

@@ -92,26 +92,36 @@ A CLI command file looks like this:
 import { PluginCommand } from '@jovotech/cli-core';
 
 export class SomeCommand extends PluginCommand {
- static id = 'build:serverless';
- static description = 'Build serverless configuration file.';
- static examples: string[] = ['jovo build:serverless'];
+ static id = '<id>';
+ static description = 'This command does something.';
+ static examples: string[] = ['jovo <id>'];
  static flags = {
  clean: flags.boolean({
- description:
- 'Deletes all platform folders and executes a clean build. If --platform is specified, it deletes only the respective platforms folder.',
+ description: 'Executes the command cleanly, making sure data is erased before execution.',
  }),
- deploy: flags.boolean({
- char: 'd',
- description: 'Runs deploy after build.',
- exclusive: ['reverse'],
+ locale: flags.string({
+ char: 'l',
+ description: 'A locale the user might provide.',
+ multiple: true,
  }),
+ // Insert global flags that are shared between commands
  ...PluginCommand.flags,
  };
-
- async run(): Promise<void> {}
+ static args = [
+ <const>{
+ name: 'platform',
+ description: 'Specifies a platform',
+ },
+ ];
+
+ async run(): Promise<void> {
+ // ...
+ }
 }
 ```
 
+Since `PluginCommand` is an extension to oclif's `Command` class, you can learn more about it's structure [here](https://oclif.io/docs/commands).
+
 ### Command Decorators
 
 You can use the `@ProjectCommand` decorator to check if the command is eligible to be run in the current working directory.
@@ -126,7 +136,7 @@ export class SomeCommand extends PluginCommand {
 }
 ```
 
-If the command is used outside a Jovo project, the CLI will display an error, letting the user know to go to a valid Jovo project directory.
+If the command is used outside of a Jovo project, the CLI will display an error, letting the user know to go to a valid Jovo project directory.
 
 ## Configuration
 
@@ -148,7 +158,7 @@ It is also possible to add configurations like this, for example:
 
 ```js
 new YourPlugin({
- someConfig: true,
+ foo: 'bar',
 }),
 ```
 
@@ -158,29 +168,24 @@ This is how a plugin that accepts config looks like:
 import { JovoCliPlugin, PluginType, PluginConfig } from '@jovotech/cli-core';
 
 export interface YourPluginConfig extends PluginConfig {
- someConfig: boolean;
+ foo: string;
  // ...
 }
 
-export class YourPlugin extends JovoCliPlugin {
+export class YourPlugin extends JovoCliPlugin<YourPluginConfig> {
  // ...
 
- constructor(config: YourPluginConfig) {
- super(config);
- }
-
  getDefaultConfig(): YourPluginConfig {
  return {
- someConfig: false,
+ foo: 'bar',
  };
  }
 }
 ```
 
 It includes the following elements:
 
-- An type interface (in the example `YourPluginConfig`) where all config options are defined.
-- A `constructor()` that passes the `config` to the `JovoCliPlugin` class.
+- An interface definition (in the example `YourPluginConfig`) where all config options are defined.
 - [A `getDefaultConfig()` method](#getdefaultconfig) that returns the default configuration options in case the config is not defined in the project configuration.
 - [A `getInitConfig()` method](#getinitconfig) that returns the configuration options that should always be added to the `jovo.project.js` file.
 
@@ -194,16 +199,16 @@ The `getDefaultConfig()` method returns the default configuration of your plugin
 import { JovoCliPlugin, PluginConfig } from '@jovotech/cli-core';
 
 export interface YourPluginConfig extends PluginConfig {
- someConfig: boolean;
+ foo: string;
  // ...
 }
 
-export class YourPlugin extends JovoCliPlugin {
+export class YourPlugin extends JovoCliPlugin<YourPluginConfig> {
  // ...
 
  getDefaultConfig(): YourPluginConfig {
  return {
- someConfig: false,
+ foo: 'bar',
  };
  }
 }
@@ -221,7 +226,7 @@ export interface YourPluginConfig extends PluginConfig {
  // ...
 }
 
-export class YourPlugin extends JovoCliPlugin {
+export class YourPlugin extends JovoCliPlugin<YourPluginConfig> {
  // ...
 
  getInitConfig(): YourPluginConfig {
@@ -240,7 +245,7 @@ new YourPlugin({
 }),
 ```
 
-You can also make use of the `RequiredOnlyWhere` type to specify which keys of your type are required, while all other elements are optional.
+You can also make use of the [`RequiredOnlyWhere`](https://www.jovo.tech/docs/types#requiredonlywhere) type to specify which keys of your type are required, while all other elements are optional.
 This allows you to differentiate between keys that are required to be set by the user, and keys that are required, but can be set in `getDefaultConfig()`.
 
 ```typescript
@@ -255,15 +260,13 @@ export interface YourPluginConfig extends PluginConfig {
 
 export type YourPluginInitConfig = RequiredOnlyWhere<YourPluginConfig, 'apiKey'>;
 
-getInitConfig(): YourPluginInitConfig {
- return {
- apiKey: '<YOUR-API-KEY>',
- };
-}
-```
-
-You can also reference multiple keys like this:
+export class YourPlugin extends JovoCliPlugin<YourPluginConfig> {
+ // ...
 
-```typescript
-export type YourPluginInitConfig = RequiredOnlyWhere<YourPluginConfig, 'apiKey' | 'someKey'>;
+ getInitConfig(): YourPluginInitConfig {
+ return {
+ apiKey: '<YOUR-API-KEY>',
+ };
+ }
+}
 ```

docs/project-config.md

@@ -215,13 +215,13 @@ const project = new ProjectConfig({
 });
 ```
 
-You can into any command, for example `before.build` or `after.build`:
+You can hook into any command, for example `before.build:platform` or `after.build:platform`:
 
 ```js
 const project = new ProjectConfig({
  // ...
  hooks: {
- 'before.build': [
+ 'before.build:platform': [
  () => {
  /* Do something here */
  },
@@ -236,7 +236,7 @@ A first example to test hooks might be to log something:
 const project = new ProjectConfig({
  // ...
  hooks: {
- 'before.build': [
+ 'before.build:platform': [
  () => console.log('Starting the build process now');
  ]
  },
@@ -254,7 +254,7 @@ const { fetchLanguageModel } = require('./hooks/fetchLanguageModel.hook.js');
 const project = new ProjectConfig({
  // ...
  hooks: {
- 'before.build': [fetchLanguageModel],
+ 'before.build:platform': [fetchLanguageModel],
  },
 });
 ```
@@ -265,7 +265,7 @@ You can also pass the `context` to a hook to access specific information:
 const project = new ProjectConfig({
  // ...
  hooks: {
- 'before.build': [(context) => console.log(`Skill ID: ${context.alexa.skillId}`)],
+ 'before.build:platform': [(context) => console.log(`Skill ID: ${context.alexa.skillId}`)],
  },
 });
 ```