Skip to content

Updates to the CLI installation guide #2121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 12, 2024
Merged

Updates to the CLI installation guide #2121

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
20f285d
Update CLI installation guide with new/updated commands and options
pwizla Jun 7, 2024
b712307
Quickly update the QSG to shorten the commands
pwizla Jun 7, 2024
460c7cc
Remove version from MongoDB "no support" caution
pwizla Jun 7, 2024
58b4859
Add pnpm support 🥳
pwizla Jun 7, 2024
a1e5a88
Port "Skip the Strapi Cloud login step" from main (v4) docs
pwizla Jun 12, 2024
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 94 additions & 27 deletions docusaurus/docs/dev-docs/installation/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A supported database is also required for any Strapi project:
| SQLite | 3 | 3 |

:::caution
Strapi v4 does not support MongoDB.
Strapi does not support MongoDB.
:::

## Creating a Strapi project
Expand All @@ -44,58 +44,125 @@ Follow the steps below to create a new Strapi project, being sure to use the app

<Tabs groupId="yarn-npm">

<TabItem value="yarn" label="Yarn">
<TabItem value="npm" label="NPM">

```bash
yarn create strapi-app my-project
# 'yarn create' creates a new project
# 'strapi-app' is the Strapi package
# 'my-project' is the name of your Strapi project
npx create-strapi@latest
```

<details>
<summary>Additional explanations for the command:</summary>

* `npx` runs a command from a npm package
* `create-strapi` is the Strapi package
* `@latest` indicates that the latest version of Strapi is used

<br/>

Instead of npx, the traditional npm command can be used too, with `npm create strapi@latest`.

Please note the additional dash between create and strapi when using npx: `npx create-strapi` vs. `npm create strapi`.
</details>

</TabItem>

<TabItem value="npm" label="NPM">
<TabItem value="yarn" label="Yarn">

```bash
yarn create strapi

```

:::note
Yarn does not support passing the version tag such as `@latest`, as opposed to npm. If you experience unexpected results with yarn and the latest version of Strapi is not installed, you might need to [run the `yarn cache clean` command](https://yarnpkg.com/cli/cache/clean) to clean your Yarn cache.
:::

</TabItem>

<TabItem value="pnpm" label="pnpm">

```bash
npx create-strapi-app@latest my-project
# 'npx' runs a command from an npm package
# 'create-strapi-app' is the Strapi package
# '@latest' indicates that the latest version of Strapi is used
# 'my-project' is the name of your Strapi project
pnpm create strapi
```

</TabItem>

</Tabs>

2. Choose an installation type:
2. Type the name of your project. If you press `Enter` instead of typing something, the default `my-strapi-project` name will be used.

:::tip
This question can be skipped by passing the project name to the command at step 1 (e.g., `npx create-strapi@latest my-strapi-project`).
:::

3. Choose whether you want to use TypeScript or not, by typing `y` for yes or `n` for no, then pressing `Enter`.<br/>If you press `Enter` without typing anything, as "yes" is the default selected option, it will create a TypeScript project.

- `Quickstart (recommended)`, which uses the default database (SQLite)
- `Custom (manual settings)`, which allows to choose your preferred database
4. Choose whether you want to use the default database type (SQLite) or not, by typing `y` for "yes" or `n` for "no", then pressing `Enter`.<br/>If you press `Enter` without typing anything, as "yes" is the default selected option, it will create a project with a SQLite database.

3. (Custom installation type only) Among the list of databases, choose a database for your Strapi project.
5. _(optional)_ If you answered `n` for "no" to the previous (default database) question, the CLI will ask for more questions about the database:

4. (Custom installation type only) Name your project's database.
* Use arrow keys to select the database type you want, then press `Enter`.
* Give the database a name, define the database host address and port, define the database admin username and password, and define whether the database will use a SSL connection.<br/>For any of these questions, if you press `Enter` without typing anything, the default value (indicated in parentheses in the terminal output) will be used.

Once all questions have been answered, the script will start creating the Strapi project.

### CLI installation options

The above installation guide only covers the basic installation option using the CLI. There are other options that can be used when creating a new Strapi project, for example:

- `--quickstart`: Directly create the project in quickstart mode.
- `--template`: Create a project with pre-made Strapi configurations (see [Templates](/dev-docs/templates)).
- `--typescript`/`--ts`: Create a project in [TypeScript](/dev-docs/typescript).
- `--no-run`: Prevent Strapi from automatically starting the server (useful in combination with `--quickstart`).
| Option | Description |
|--------|---------------------------------------------------------|
| `--no-run` | Do not start the application after it is created |
| `--ts`<br/>`--typescript` | Initialize the project with TypeScript (default) |
| `--js`<br/>`--javascript` | Initialize the project with JavaScript |
| `--use-npm` | Force the usage of [npm](https://www.npmjs.com/) as the project package manager |
| `--use-yarn` | Force the usage of [yarn](https://yarnpkg.com/) as the project package manager |
| `--use-pnpm` | Force the usage of [pnpm](https://pnpm.io/) as the project package manager |
| `--template` | Create a project with pre-made Strapi configurations (see [Templates](/dev-docs/templates)). |
| `--dbclient <dbclient>` | Define the database client to use by replacing `<dbclient>` in the command by one of the these values:<ul><li>`sql` for a SQLite database (default)</li><li>`postgres` for a PostgreSQL database</li><li>`mysql` for a MySQL database</li></ul> |
| `--dbhost <dbhost>` | Define the database host to use by replacing `<dbclient>` in the command by the value of your choice |
| `--dbport <dbport>` | Define the database port to use by replacing `<dbclient>` in the command by the value of your choice |
| `--dbname <dbname>` | Define the database name to use by replacing `<dbclient>` in the command by the value of your choice |
| `--dbusername <dbusername>` | Define the database username to use by replacing `<dbclient>` in the command by the value of your choice |
| `--dbpassword <dbpassword>` | Define the database password to use by replacing `<dbclient>` in the command by the value of your choice |
| `--dbssl <dbssl>` | Define that SSL is used with the database, by passing `--dbssl=true` (No SSL by default) |
| `--dbfile <dbfile>` | For SQLite databases, define the database file path to use by replacing `<dbclient>` in the command by the value of your choice |
| `--quickstart` | (**Deprecated in Strapi 5**)<br/>Directly create the project in quickstart mode. |

:::note Notes
* If you do not pass a `--use-yarn|npm|pnpm` option, the installation script will use whatever package manager was used with the create command to install all dependencies (e.g., `npm create strapi` will install all the project's dependencies with npm).
* For additional information about database configuration, please refer to the [database configuration documentation](/dev-docs/configurations/database#configuration-structure).
* Experimental Strapi versions are released every Tuesday through Saturday at midnight GMT. You can create a new Strapi application based on the latest experimental release using `npx create-strapi@experimental`. Please use these experimental builds at your own risk. It is not recommended to use them in production.
:::

For more information on available flags, see our [CLI documentation](/dev-docs/cli).

Strapi also offers a starters CLI to create a project with a pre-made frontend application (see [our dedicated blog post](https://strapi.io/blog/announcing-the-strapi-starter-cli)).
### Skipping the Strapi Cloud login step

:::tip
Experimental Strapi versions are released every Tuesday through Saturday at midnight GMT. You can create a new Strapi application based on the latest experimental release using `npx create-strapi-app@experimental`.
When the installation script runs, the terminal will first ask you if you want to login/signup. Choosing `Login/signup` will create a free, 14-day trial [Strapi Cloud](/cloud/intro#what-is-strapi-cloud) project as described in the [Quick Start Guide](/dev-docs/quick-start).

Please use these experimental builds at your own risk. It is not recommended to use them in production.
:::
If you prefer skipping this Strapi Cloud login part, use the arrow keys to select `Skip`. The script will resume and create a local project. To deploy this project and host it online, you could later choose to:
- host it yourself by pushing the project's code to a repository (e.g., on GitHub) before following a [3rd-party deployment guide](/dev-docs/deployment),
- or use the [Cloud CLI](/cloud/cli/cloud-cli) commands to login to Strapi Cloud and deploy your project there.

If you want to host your project yourself and are not already familiar with GitHub, the following togglable content should get you started👇.

<details>
<summary>Steps required to push your Strapi project code to GitHub:</summary>

1. In the terminal, ensure you are still in the folder that hosts the Strapi project you created.
2. Run the `git init` command to initialize git for this folder.
3. Run the `git add .` command to add all modified files to the git index.
4. Run the `git commit -m "Initial commit"` command to create a commit with all the added changes.
5. Log in to your GitHub account and [create a new repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). Give the new repository a name, for instance `my-first-strapi-project`, and remember this name.
6. Go back to the terminal and push your local repository to GitHub:

a. Run a command similar to the following: `git remote add origin git@github.com:yourname/my-first-strapi-project.git`, ensuring you replace `yourname` by your own GitHub profile name, and `my-first-strapi-project` by the actual name you used at step 4.

b. Run the `git push --set-upstream origin main` command to finally push the commit to your GitHub repository.

Additional information about using git with the command line interface can be found in the [official GitHub documentation](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#adding-a-local-repository-to-github-using-git).

</details>

## Running Strapi

Expand Down
4 changes: 2 additions & 2 deletions docusaurus/docs/dev-docs/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,11 @@ Follow the steps below by clicking on the togglable content to read more instruc
Run the following command in a terminal:

```bash
npx create-strapi-app@beta my-project --quickstart
npx create-strapi@beta my-project --quickstart
Copy link
Member

@alexandrebodin alexandrebodin Jun 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For v5 we should definitely remove the --quickstart option from the guide so users can see all the options instead. We consider it to be deprecated and will be removed in v6
Copy link
Collaborator Author

@pwizla pwizla Jun 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, Alex!
But if I do this, I need to update the rest of the Quick Start Guide (more questions to answer, etc.).

I won't do it now, because the Quick Start Guide will again change in the following weeks (re. Cloud CLI) and it takes time to update it.

At least now they could use the shorter commands and (hopefully) have roughly the same experience than in the current Quick Start Guide ( = before the Cloud CLI)
Copy link
Collaborator Author

@pwizla pwizla Jun 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In short, for the final (stable, in September) version of the v5 Quick Start Guide I'll remove the --quickstart and ensure users experience the new workflow exactly like it's described. For now, too time consuming in regards of all the other tasks I have to do.
Copy link
Member

@alexandrebodin alexandrebodin Jun 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:+1
```

:::info
The `quick start` installation sets up Strapi with a SQLite database. Other databases and installation options are available (see [CLI installation guide](/dev-docs/installation/cli)).
The `--quickstart` installation sets up Strapi with a SQLite database. Other databases and installation options are available (see [CLI installation guide](/dev-docs/installation/cli)).
:::

</details>
Expand Down