Merge pull request #1273 from FoalTS/docs-cli

Prefer using @foal/cli locally than globally

.github/CONTRIBUTING.MD

@@ -146,7 +146,7 @@ All of major releases are supported for at least 18 months.
 
 ### `@foal/cli` Package Structure
 
-The directory `src/generate/` contains the source code of the commands `foal createapp` and `foal generate`.
+The directory `src/generate/` contains the source code of the commands `npx @foal/cli createapp` and `npx foal generate`.
 
 Here is the list of its sub-directories:
 

README.md

@@ -55,10 +55,9 @@ First install [Node.Js and npm](https://nodejs.org/en/download/).
 ### Create a new app
 
 ```
-$ npm install -g @foal/cli
-$ foal createapp my-app
-$ cd my-app
-$ npm run dev
+npx @foal/cli createapp my-app
+cd my-app
+npm run dev
 ```
 
 The development server is started! Go to `http://localhost:3001` and find our welcoming page!

docs/blog/version-4.5-release-notes.md

@@ -14,3 +14,24 @@ Version 4.5 of [Foal](https://foalts.org/) is out!
 
 <!--truncate-->
 
+## Global use of CLI deprecated
+
+In previous versions, the tutorial suggested installing the CLI globally to create a new application or generate files. However, it is considered bad practice to install a dependency globally for local use.
+
+In addition, the CLI was also installed locally so that the build command would work when deploying the application to a CI or to production. This was maintaining two versions of the CLI.
+
+To correct this, in the documentation and examples, the CLI is now always installed and used locally. To use it, simply add `npx` before each command (except for `createapp`).
+
+```bash
+# Before
+foal createapp my-app
+
+foal generate script foobar
+foal createsecret
+
+# After
+npx @foal/cli createapp my-app
+
+npx foal generate script foobar
+npx foal createsecret
+```

docs/docs/README.md

@@ -35,10 +35,9 @@ Great attention is paid to the stability of the product. You can find out more b
 ## Get Started
 
 ```
-> npm install -g @foal/cli
-> foal createapp my-app
-> cd my-app
-> npm run dev
+npx @foal/cli createapp my-app
+cd my-app
+npm run dev
 ```
 
 The development server is started! Go to `http://localhost:3001` and find our welcoming page!

docs/docs/architecture/configuration.md

@@ -63,7 +63,7 @@ module.exports = {
 > When creating a new project, you can also add the flag `--yaml` to have all the configuration directly generated in YAML.
 >
 > ```
-> foal createapp my-app --yaml
+> npx @foal/cli createapp my-app --yaml
 > ```
 >
 > The extension of the YAML files must be `.yml`.

docs/docs/architecture/controllers.md

@@ -4,7 +4,7 @@ title: Controllers
 
 
 ```sh
-foal generate controller my-controller
+npx foal generate controller my-controller
 ```
 
 ```typescript

docs/docs/architecture/hooks.md

@@ -4,7 +4,7 @@ title: Hooks
 
 
 ```sh
-foal generate hook my-hook
+npx foal generate hook my-hook
 ```
 
 ## Description

docs/docs/architecture/services-and-dependency-injection.md

@@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem';
 
 
 ```sh
-foal generate service my-service
+npx foal generate service my-service
 ```
 
 ```typescript

docs/docs/authentication/jwt.md

@@ -20,10 +20,10 @@ Foal offers a package, named `@foal/jwt`, to manage authentication / authorizati
 
 ## Generate & Provide a Secret
 
-In order to use JWTs, you must provide a secret to *sign* your tokens. If you do not already have your own, you can generate one with the `foal createsecret` command.
+In order to use JWTs, you must provide a secret to *sign* your tokens. If you do not already have your own, you can generate one with the `npx foal createsecret` command.
 
 ```sh
-$ foal createsecret
+npx foal createsecret
 Ak0WcVcGuOoFuZ4oqF1tgqbW6dIAeSacIN6h7qEyJM8=
 ```
 

docs/docs/authentication/quick-start.md

@@ -212,7 +212,7 @@ export class ApiController {
 First, generate a base64-encoded secret.
 
 ```bash
-foal createsecret
+npx foal createsecret
 ```
 
 Save this secret in a `.env` file.
@@ -516,7 +516,7 @@ export class ApiController {
 First, generate a base64-encoded secret.
 
 ```bash
-foal createsecret
+npx foal createsecret
 ```
 
 Save this secret in a `.env` file.

docs/docs/authentication/session-tokens.md

@@ -635,7 +635,7 @@ module.exports = {
 #### Revoking One Session
 
 ```
-foal g script revoke-session
+npx foal g script revoke-session
 ```
 
 Open `scripts/revoke-session.ts` and update its content.
@@ -675,13 +675,13 @@ npm run build
 Run the script.
 
 ```
-foal run revoke-session token="lfdkszjanjiznr"
+npx foal run revoke-session token="lfdkszjanjiznr"
 ```
 
 #### Revoking All Sessions
 
 ```
-foal g script revoke-all-sessions
+npx foal g script revoke-all-sessions
 ```
 
 Open `scripts/revoke-all-sessions.ts` and update its content.
@@ -709,7 +709,7 @@ npm run build
 Run the script.
 
 ```
-foal run revoke-all-sessions
+npx foal run revoke-all-sessions
 ```
 
 ### Query All Sessions of a User

docs/docs/authentication/user-class.md

@@ -48,7 +48,7 @@ You can use the `create-user` shell script (located in `src/scripts`) to create
 
 ```sh
 npm run build
-foal run create-user
+npx foal run create-user
 ```
 
 ## Example (email and password)
@@ -134,7 +134,7 @@ You can now create a new user with these commands:
 
 ```sh
 npm run build
-foal run create-user [email protected] password=mary_password
+npx foal run create-user [email protected] password=mary_password
 ```
 
 ## Using another ORM/ODM

docs/docs/authorization/groups-and-permissions.md

@@ -41,7 +41,7 @@ async function main() {
 
 Create a new script with this command:
 ```
-foal generate script create-perm
+npx foal generate script create-perm
 ```
 
 Replace the content of the new created file `src/scripts/create-perm.ts` with the following:
@@ -84,7 +84,7 @@ export async function main(args: { codeName: string, name: string }) {
 Then you can create a permission through the command line.
 ```sh
 npm run build
-foal run create-perm name="Permission to access the secret" codeName="access-secret"
+npx foal run create-perm name="Permission to access the secret" codeName="access-secret"
 ```
 
 ## Groups
@@ -125,7 +125,7 @@ async function main() {
 
 Create a new script with this command:
 ```
-foal generate script create-group
+npx foal generate script create-group
 ```
 
 Replace the content of the new created file `src/scripts/create-group.ts` with the following:
@@ -180,8 +180,8 @@ export async function main(args: { codeName: string, name: string, permissions:
 Then you can create a group through the command line.
 ```sh
 npm run build
-foal run create-perm name="Permission to delete users" codeName="delete-users"
-foal run create-group name="Administrators" codeName="admin" permissions="[ \"delete-users\" ]"
+npx foal run create-perm name="Permission to delete users" codeName="delete-users"
+npx foal run create-group name="Administrators" codeName="admin" permissions="[ \"delete-users\" ]"
 ```
 
 ## Users
@@ -289,7 +289,7 @@ Then you can create a user with their permissions and groups through the command
 
 ```sh
 npm run build
-foal run create-user userPermissions="[ \"my-first-perm\" ]" groups="[ \"my-group\" ]"
+npx foal run create-user userPermissions="[ \"my-first-perm\" ]" groups="[ \"my-group\" ]"
 ```
 
 ## Fetching a User with their Permissions

docs/docs/cli/code-generation.md

@@ -6,7 +6,7 @@ title: Code Generation
 ## Create a project
 
 ```shell
-foal createapp my-app
+npx @foal/cli createapp my-app
 ```
 
 Create a new directory with all the required files to get started.
@@ -18,15 +18,15 @@ If you specify the flag `--yaml`, the new project will use YAML format for its c
 ## Create a controller
 
 ```shell
-foal g controller <name>
+npx foal g controller <name>
 ```
 
 Create a new controller in `./src/app/controllers`, in `./controllers` or in the current directory depending on which folders are found.
 
 *Example*
 ```shell
-foal g controller auth
-foal g controller api/product
+npx foal g controller auth
+npx foal g controller api/product
 ```
 
 *Output*
@@ -44,15 +44,15 @@ src/
 ### The `--register` flag
 
 ```shell
-foal g controller <name> --register
+npx foal g controller <name> --register
 ```
 
 If you wish to automatically create a new route attached to this controller, you can use the `--register` flag to do so.
 
 *Example*
 ```shell
-foal g controller api --register
-foal g controller api/product --register
+npx foal g controller api --register
+npx foal g controller api/product --register
 ```
 
 *Output*
@@ -89,15 +89,15 @@ export class ApiController {
 ## Create an entity 
 
 ```shell
-foal g entity <name>
+npx foal g entity <name>
 ```
 
 Create a new entity in `./src/app/entities`, in `./entities` or in the current directory depending on which folders are found.
 
 *Example*
 ```shell
-foal g entity user
-foal g entity business/product
+npx foal g entity user
+npx foal g entity business/product
 ```
 
 *Output*
@@ -115,15 +115,15 @@ src/
 ## Create REST API
 
 ```shell
-foal g rest-api <name>
+npx foal g rest-api <name>
 ```
 
 Create a new controller and a new entity to build a basic REST API. Depending on which directories are found, they will be generated in `src/app/{entities}|{controllers}/` or in `{entities}|{controllers}/`.
 
 *Example*
 ```shell
-foal g rest-api order
-foal g rest-api api/product
+npx foal g rest-api order
+npx foal g rest-api api/product
 ```
 
 *Output*
@@ -148,24 +148,24 @@ If you wish to automatically create a new route attached to this controller, you
 
 *Example*
 ```shell
-foal g controller api --register
-foal g controller api/product --register
+npx foal g controller api --register
+npx foal g controller api/product --register
 ```
 
 See the page [REST Blueprints](../common/rest-blueprints.md) for more details.
 
 ## Create a hook
 
 ```shell
-foal g hook <name>
+npx foal g hook <name>
 ```
 
 Create a new hook in `./src/app/hooks`, in `./hooks` or in the current directory depending on which folders are found.
 
 *Example*
 ```shell
-foal g hook log
-foal g hook auth/admin-required
+npx foal g hook log
+npx foal g hook auth/admin-required
 ```
 
 *Output*
@@ -184,23 +184,23 @@ src/
 ## Create a script
 
 ```shell
-foal g script <name>
+npx foal g script <name>
 ```
 
 Create a new shell script in `src/scripts` regardless of where you run the command.
 
 ## Create a service
 
 ```shell
-foal g service <name>
+npx foal g service <name>
 ```
 
 Create a new service in `./src/app/services`, in `./services` or in the current directory depending on which folders are found.
 
 *Example*
 ```shell
-foal g service auth
-foal g service apis/github
+npx foal g service auth
+npx foal g service apis/github
 ```
 
 *Output*

docs/docs/cli/commands.md

@@ -10,4 +10,4 @@ FoalTS provides several commands to help you build and develop your app.
 | `npm run dev` | Build the source code and start the server. If a file changes then the code is rebuilt and the server reloads. This is usually **the only command that you need during development** |
 | `npm run build` | Build the app code located in the `src/` directory (test files are ignored). |
 | `npm run start` | Start the server from the built files. |
-| `foal upgrade [version]` | Upgrade all local `@foal/*` dependencies and dev dependencies to the given version. If no version is provided, then the command upgrades to the latest version of Foal. An additional flag `--no-install` can be provided to not trigger the npm or yarn installation. |
+| `npx foal upgrade [version]` | Upgrade all local `@foal/*` dependencies and dev dependencies to the given version. If no version is provided, then the command upgrades to the latest version of Foal. An additional flag `--no-install` can be provided to not trigger the npm or yarn installation. |

docs/docs/cli/shell-scripts.md

@@ -9,7 +9,7 @@ Sometimes we have to execute some tasks from the command line. These tasks can s
 
 A shell script is just a TypeScript file located in the `src/scripts`. It must export a `main` function that is then called when running the script.
 
-Let's create a new one with the command line: `foal g script display-users`. A new file with a default template should appear in you `src/scripts` directory.
+Let's create a new one with the command line: `npx foal g script display-users`. A new file with a default template should appear in you `src/scripts` directory.
 
 ## Write Scripts
 
@@ -55,9 +55,9 @@ npm run build
 Then you can execute it with this command:
 
 ```shell
-foal run my-script # or foal run-script my-script
+npx foal run my-script # or npx foal run-script my-script
 ```
 
-> You can also provide additionnal arguments to your script (for example: `foal run my-script foo=1 bar='[ 3, 4 ]'`). The default template in the generated scripts shows you how to handle such behavior.
+> You can also provide additionnal arguments to your script (for example: `npx foal run my-script foo=1 bar='[ 3, 4 ]'`). The default template in the generated scripts shows you how to handle such behavior.
 
 > If you want your script to recompile each time you save the file, you can run `npm run dev` in a separate terminal.