Skip to content
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.

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

simlify auto-install instructions #867

Merged
merged 17 commits into from
Jul 5, 2022
Merged
Changes from 13 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 41 additions & 77 deletions src/pages/en/install/auto.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,14 @@ Ready to install Astro? Follow our automatic or manual set-up guide to get start

#### Installation

`create-astro` is the fastest, easiest way to start a new Astro project from scratch.
`create-astro` is the fastest way to start a new Astro project from scratch.

## 1. Run the CLI

Run the following command in your terminal to start our handy install wizard, `create-astro`. This will walk you through creating your very first Astro project.
:::tip[Online previews]
Prefer to try Astro in your browser? Visit [astro.new](https://astro.new/) to browse our starter templates and spin up a new Astro project without ever leaving your browser.
:::
## 1. Run the Setup Wizard

No need to create a new directory first! The wizard will create a project folder for you.
Run the following command in your terminal to start our handy install wizard, `create-astro`.

```shell
# npm
Expand All @@ -36,62 +37,44 @@ yarn create astro
pnpm create astro@latest
```

The `create-astro` wizard will walk you through setting up a new Astro project, by asking the following questions:

Depending on your package manager, you may be prompted to confirm you want to install `create-astro@latest`. You will then be asked to specify a project folder (e.g. `./my-astro-site`) which will create a new directory.

### Choose a Starter Template
You will then see a short list of starter templates to choose from:
- `Just the basics`: A great starter template for anyone wanting to explore Astro.
- `Blog`, `Documentation`, `Portfolio`: opinionated themes for specific use-cases.
- `Completely empty`: A template that just includes the bare minimium to get started.

Use the arrow keys (up and down) to navigate to the template you want to install, then press return (enter) to submit.

:::tip[Online previews]
Want to check out the templates in your browser before choosing? Visit [astro.new](https://astro.new/)
:::
FredKSchott marked this conversation as resolved.
Show resolved Hide resolved

### Install Dependencies (optional)
delucis marked this conversation as resolved.
Show resolved Hide resolved
The wizard will offer to run an `install` command for you at this time, which is optional.
1. Where would you like to create your new Astro project?

Astro must be installed in an empty folder. Type in a name for your new project directory.

```bash
./my-astro-site
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
```

:::caution
If you do not do so at this time, you will need to [install dependencies](/en/install/auto/#2-install-dependencies) after the wizard has finished, before starting your project.
:::

### Install any Official Astro Integrations (optional)
You will be given the option at this time to add any [additional UI frameworks](/en/core-concepts/framework-components/) (React, Svelte, Vue, Solid, Preact, Lit) and then other Astro official integrations (Tailwind, Partytown, Sitemap) by running `astro add --yes`


To select which Astro integrations, if any, you would like to include in your project, use the arrow keys (up and down) to navigate and the space bar to toggle between selected states. You can select multiple items at once, or you can continue without selecting any integrations.


When you are satisfied with your selection, press return (enter) to submit.

:::note
These integrations, and any [Astro community integrations](https://astro.build/integrations/), can also be added later by following the instructions in our [integrations guide](/en/guides/integrations-guide/).
:::
1. Which template would you like to use?

Select from the following list:
- [Just the Basics](https://github.com/withastro/astro/tree/main/examples/basics) - includes a typical project structure as a model
- [Blog](https://github.com/withastro/astro/tree/main/examples/blog) - includes an index page and a folder with first blog post
- [Docs](https://github.com/withastro/astro/tree/main/examples/docs) - includes sidebar nav, page table of contents, and multi-language support
- [Portfolio](https://github.com/withastro/astro/tree/main/examples/portfolio) - styled and ready to go with portfolio and about pages
- [Completely Empty](https://github.com/withastro/astro/tree/main/examples/minimal) - just a single page


After selecting your integrations to add, you should see the following terminal message notifying you of the changes that `create-astro` will apply to your project's `astro.config.mjs`:
1. Would you like to install dependencies with your package manager? (Y/n)

```bash
Astro will make the following changes to your config file:
```
**Optional**: You can install dependencies yourself after setup!

This message should show that your chosen integrations have been successfully added to your project configuration. (If not, you can always add them manually later.)
1. Initialize a Git repository? (Y/n)

**Optional**: You can run `git init` later!

### Initialize a `.git` Repository (optional)
<!-- You do not need to create a new directory for your project before running the wizard. As a part of setup, the `create-astro` wizard will ask you where your new project should live and will create a new folder for it if needed.

At this final step, you can choose to initialize a git repository in your new directory. This is optional, but useful if you plan to use the tool [Git](https://git-scm.com/) for your project.
Before running, some package managers may prompt you to confirm that you want to install the latest version of `create-astro` (`create-astro@latest`). This is expected, and it is okay to accept this prompt so that the `create-astro` wizard can run on your machine. -->

### Next Steps
## 2. Install NPM Dependencies
delucis marked this conversation as resolved.
Show resolved Hide resolved

When the `create-astro` install wizard is complete, you should see some recommended instructions ("Next Steps") on your screen to follow that will help you complete setup and start your new project.
If you already installed your dependencies during `create-astro` setup, then you can skip this and move on to the next step.

## 2. Install Dependencies
Astro is distributed via the [npm ecosystem](https://www.npmjs.com/package/astro), so you will need to install it using `npm` or another npm package manager of your choice.

If you did not install your project's dependencies using the wizard, you will now need to do so using your preferred package manager:

```bash
# npm
Expand All @@ -102,22 +85,20 @@ yarn

# pnpm
pnpm install

```


## 3. Start Astro ✨
FredKSchott marked this conversation as resolved.
Show resolved Hide resolved

You can expect to use Astro's built-in dev server for most of your project development. This is how you will run your project locally during development.
Astro's built-in development server comes with everything that you need for project development. The `astro dev` command will start the local development server so that you can see your new website in action for the very first time.

To start, use your package manager to run your pre-configured start script:
Every starter template comes with a pre-configured `dev` script that runs `astro dev` for you. Use your package manager to run this script:

```bash
# npm
npm run dev

# yarn
yarn start
yarn run dev

# pnpm
pnpm run dev
Expand All @@ -127,33 +108,16 @@ If all goes well, Astro should now be serving your project on [http://localhost:

Astro will listen for live file changes in your `src/` directory, so you will not need to restart the server as you make changes during development.

If you aren't able to open your project in the browser, go back to the terminal where you ran the `start` command to see what went wrong.

## 4. Deploy to the web

It's time to deploy your project to the web! Run the `build` command in your project to build your static website to a new `dist/` folder in your project.

```bash
# npm
npm run build

# yarn
yarn build

# pnpm
pnpm run build
```

When the command finishes, you should have a new `dist/` folder in your project that you can deploy directly to your favorite web host.

To get started hosting your website for free, check out our proud hosting partner, [Netlify](https://www.netlify.com/). For instructions on deploying to whatever host you choose, read our detailed [deployment guide](/en/guides/deploy/).
If you aren't able to open your project in the browser, go back to the terminal where you ran the `start` command and look to see if an error occurred, or if your project is being served at a different URL than the one linked to above.

## Next Steps

Success! Now you're ready to start developing!
Success! You are now ready to start building with Astro! 🥳

Here are a few topics that we recommend exploring next. You can read them in any order. You can even leave our documentation for a bit and go play in your new Astro project codebase, coming back here whenever you run into trouble or have a question.

📚 Learn more about Astro’s project structure in our [Project Structure guide](/en/core-concepts/project-structure/).
📚 **Add a framework:** Learn how to extend Astro with support for React, Svelte, Tailwind and more using `npx astro add` in our [Integrations guide](/en/guides/integrations-guide/).

📚 Learn more about Astro’s component syntax in our [Astro Components guide](/en/core-concepts/astro-components/).
📚 **Deploy your site:** Learn how to build and deploy an Astro project to the web in our [Deployment guide](/en/guides/deploy/).

📚 Learn more about Astro’s file-based routing in our [Routing guide](/en/core-concepts/astro-pages/).
📚 **Understand your codebase:** Learn more about Astro’s project structure in our [Project Structure guide](/en/core-concepts/project-structure/).