From 5cb38ee435fb08bbe9890458aab542c59d8a69e5 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 21 Nov 2024 15:05:23 -0400 Subject: [PATCH] streamlined install plus develop and build pages (#10060) Co-authored-by: Armand Philippot Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> Co-authored-by: delucis <357379+delucis@users.noreply.github.com> --- astro.sidebar.ts | 2 +- src/content/docs/en/develop-and-build.mdx | 146 ++++++++++++ .../migrate-to-astro/from-docusaurus.mdx | 2 +- .../guides/migrate-to-astro/from-eleventy.mdx | 2 +- .../guides/migrate-to-astro/from-gatsby.mdx | 2 +- .../guides/migrate-to-astro/from-gitbook.mdx | 2 +- .../guides/migrate-to-astro/from-gridsome.mdx | 2 +- .../en/guides/migrate-to-astro/from-hugo.mdx | 2 +- .../guides/migrate-to-astro/from-jekyll.mdx | 2 +- .../guides/migrate-to-astro/from-nextjs.mdx | 2 +- .../guides/migrate-to-astro/from-nuxtjs.mdx | 2 +- .../guides/migrate-to-astro/from-pelican.mdx | 2 +- .../migrate-to-astro/from-sveltekit.mdx | 2 +- .../guides/migrate-to-astro/from-vuepress.mdx | 2 +- .../migrate-to-astro/from-wordpress.mdx | 2 +- src/content/docs/en/install-and-setup.mdx | 222 +++++------------- src/content/docs/en/recipes/bun.mdx | 2 +- src/content/docs/it/recipes/bun.mdx | 2 +- 18 files changed, 225 insertions(+), 175 deletions(-) create mode 100644 src/content/docs/en/develop-and-build.mdx diff --git a/astro.sidebar.ts b/astro.sidebar.ts index c8b1abbc7bf30..02e976d6e3efb 100644 --- a/astro.sidebar.ts +++ b/astro.sidebar.ts @@ -18,7 +18,7 @@ export const sidebar = [ items: ['concepts/why-astro', 'concepts/islands', 'tutorial/0-introduction'], }), group('start.newProject', { - items: ['install-and-setup', 'basics/project-structure'], + items: ['install-and-setup', 'basics/project-structure', 'develop-and-build',], }), group('start.config', { items: [ diff --git a/src/content/docs/en/develop-and-build.mdx b/src/content/docs/en/develop-and-build.mdx new file mode 100644 index 0000000000000..ed60bc7b29df8 --- /dev/null +++ b/src/content/docs/en/develop-and-build.mdx @@ -0,0 +1,146 @@ +--- +title: Develop and build +description: 'How to start working on a new project.' +i18nReady: true +--- +import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components'; +import ReadMore from '~/components/ReadMore.astro'; + +Once you have an Astro project, now you're ready to build with Astro! 🚀 + +## Edit your project + +To make changes to your project, open your project folder in your code editor. Working in development mode with the dev server running allows you to see updates to your site as you edit the code. + +You can also [customize aspects of your development environment](#configure-your-dev-environment) such as configuring TypeScript or installing the official Astro editor extensions. + +### Start the Astro dev server + +Astro comes with a built-in development server that has everything you need for project development. The `astro dev` CLI command will start the local development server so that you can see your new website in action for the very first time. + +Every starter template comes with a pre-configured script that will run `astro dev` for you. After navigating into your project directory, use your favorite package manager to run this command and start the Astro development server. + + + + ```shell + npm run dev + ``` + + + ```shell + pnpm run dev + ``` + + + ```shell + yarn run dev + ``` + + + + +If all goes well, Astro will now be serving your project on [http://localhost:4321/](http://localhost:4321/). Visit that link in your browser and see your new site! + +### Work in development mode + +Astro will listen for live file changes in your `src/` directory and update your site preview as you build, so you will not need to restart the server as you make changes during development. You will always be able to see an up-to-date version of your site in your browser when the dev server is running. + +When viewing your site in the browser, you'll have access to the [Astro dev toolbar](/en/guides/dev-toolbar/). As you build, it will help you inspect your [islands](/en/concepts/islands/), spot accessibility issues, and more. + +If you aren't able to open your project in the browser after starting the dev server, go back to the terminal where you ran the `dev` command and check the message displayed. It should tell you if an error occurred, or if your project is being served at a different URL than [http://localhost:4321/](http://localhost:4321/). + +## Build and preview your site + +To check the version of your site that will be created at build time, quit the dev server (Ctrl + C) and run the appropriate build command for your package manager in your terminal: + + + + ```shell + npm run build + ``` + + + ```shell + pnpm build + ``` + + + ```shell + yarn run build + ``` + + + +Astro will build a deploy-ready version of your site in a separate folder (`dist/` by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production. If TypeScript is configured to `strict` or `strictest`, the `build` script will also check your project for type errors. + +When the build is finished, run the appropriate `preview` command (e.g. `npm run preview`) in your terminal and you can view the built version of your site locally in the same browser preview window. + +Note that this previews your code as it existed when the build command was last run. This is meant to give you a preview of how your site will look when it is deployed to the web. Any later changes you make to your code after building will **not** be reflected while you preview your site until you run the build command again. + +Use (Ctrl + C) to quit the preview and run another terminal command, such as restarting the dev server to go back to [working in development mode](#work-in-development-mode) which does update as you edit to show a live preview of your code changes. + +Read more about [the Astro CLI](/en/reference/cli-reference/) and the terminal commands you will use as you build with Astro. + +:::tip +You may wish to [deploy your new site right away](/en/guides/deploy/), before you begin to add or change too much code. This is helpful to get a minimal, working version of your site published and can save you extra time and effort troubleshooting your deployment later. +::: + +## Next Steps + +Success! You are now ready to start building with Astro! 🥳 + +Here are a few things 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. + +### Configure your dev environment + +Explore the guides below to customize your development experience. + + + + + + + +### Explore Astro's Features + + + + + + + + +### Take the introductory tutorial + +Build a fully functional Astro blog starting from a single blank page in our [introductory tutorial](/en/tutorial/0-introduction/). + +This is a great way to see how Astro works and walks you through the basics of pages, layouts, components, routing, islands, and more. It also includes an optional, beginner-friendly unit for those newer to web development concepts in general, which will guide you through installing the necessary applications on your computer, creating a GitHub account, and deploying your site. + diff --git a/src/content/docs/en/guides/migrate-to-astro/from-docusaurus.mdx b/src/content/docs/en/guides/migrate-to-astro/from-docusaurus.mdx index 6ebc960cf11e1..c65f4d448d2a1 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-docusaurus.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-docusaurus.mdx @@ -46,7 +46,7 @@ When you rebuild your Docusaurus site in Astro, you will notice some important d To convert a Docusaurus documentation site to Astro, start with our official [Starlight docs theme starter template](https://starlight.astro.build), or explore more community docs themes in our [theme showcase](https://astro.build/themes?search=&categories%5B%5D=docs). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-eleventy.mdx b/src/content/docs/en/guides/migrate-to-astro/from-eleventy.mdx index 287df7c6715a0..938abf4027f72 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-eleventy.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-eleventy.mdx @@ -37,7 +37,7 @@ When you rebuild your Eleventy (11ty) site in Astro, you will notice some import To convert an Eleventy blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx index 34cbe2ca62e43..4b3413f2cb914 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx @@ -45,7 +45,7 @@ Each project migration will look different, but there are some common actions yo ### Create a new Astro project Use the `create astro` command for your package manager to launch Astro's CLI wizard or choose a community theme from the [Astro Theme Showcase](https://astro.build/themes). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters (e.g. `docs`, `blog`, `portfolio`). Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters (e.g. `docs`, `blog`, `portfolio`). Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-gitbook.mdx b/src/content/docs/en/guides/migrate-to-astro/from-gitbook.mdx index dc92f3f4756ed..e6c0ac4ae5802 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-gitbook.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-gitbook.mdx @@ -37,7 +37,7 @@ When you migrate your GitBook docs to Astro, you will notice some important diff To convert a GitBook documentation site to Astro, start with our official [Starlight docs theme starter template](https://starlight.astro.build), or explore more community docs themes in our [theme showcase](https://astro.build/themes?search=&categories%5B%5D=docs). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-gridsome.mdx b/src/content/docs/en/guides/migrate-to-astro/from-gridsome.mdx index c269cd57e0847..f98c7758af7b6 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-gridsome.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-gridsome.mdx @@ -39,7 +39,7 @@ When you rebuild your Gridsome site in Astro, you will notice some important dif To convert a Gridsome blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-hugo.mdx b/src/content/docs/en/guides/migrate-to-astro/from-hugo.mdx index 1fd7d090b700e..40fbf93531a9d 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-hugo.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-hugo.mdx @@ -39,7 +39,7 @@ When you rebuild your Hugo site in Astro, you will notice some important differe To convert a Hugo blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-jekyll.mdx b/src/content/docs/en/guides/migrate-to-astro/from-jekyll.mdx index 234b33d8cd635..72acaca4c0eb4 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-jekyll.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-jekyll.mdx @@ -37,7 +37,7 @@ When you rebuild your Jekyll site in Astro, you will notice some important diffe To convert a Jekyll blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx b/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx index 61bb7efee0318..71d0ed0fc38ee 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx @@ -43,7 +43,7 @@ Each project migration will look different, but there are some common actions yo Use the `create astro` command for your package manager to launch Astro's CLI wizard or choose a community theme from the [Astro Theme Showcase](https://astro.build/themes). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters (e.g. `docs`, `blog`, `portfolio`). Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters (e.g. `docs`, `blog`, `portfolio`). Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx b/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx index f8827c36a5985..113b02fb99435 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx @@ -44,7 +44,7 @@ Each project migration will look different, but there are some common actions yo ### Create a new Astro project Use the `create astro` command for your package manager to launch Astro's CLI wizard or choose a community theme from the [Astro Theme Showcase](https://astro.build/themes). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters (e.g. `docs`, `blog`, `portfolio`). Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters (e.g. `docs`, `blog`, `portfolio`). Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-pelican.mdx b/src/content/docs/en/guides/migrate-to-astro/from-pelican.mdx index d41cd18c527fc..00ead9030480b 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-pelican.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-pelican.mdx @@ -35,7 +35,7 @@ When you rebuild your Pelican site in Astro, you will notice some important diff To convert a Pelican documentation site to Astro, start with our official [Starlight docs theme starter template](https://starlight.astro.build), or explore more community themes in our [theme showcase](https://astro.build/themes/). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-sveltekit.mdx b/src/content/docs/en/guides/migrate-to-astro/from-sveltekit.mdx index 48c7451cfc9bb..979cf6cc08e47 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-sveltekit.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-sveltekit.mdx @@ -42,7 +42,7 @@ When you rebuild your SvelteKit site in Astro, you will notice some important di To convert a SvelteKit blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-vuepress.mdx b/src/content/docs/en/guides/migrate-to-astro/from-vuepress.mdx index 86d311f079868..62ce180122b28 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-vuepress.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-vuepress.mdx @@ -37,7 +37,7 @@ When you rebuild your VuePress site in Astro, you will notice some important dif To convert a VuePress documentation site to Astro, start with our official [Starlight docs theme starter template](https://starlight.astro.build), or explore more community docs themes in our [theme showcase](https://astro.build/themes?search=&categories%5B%5D=docs). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/guides/migrate-to-astro/from-wordpress.mdx b/src/content/docs/en/guides/migrate-to-astro/from-wordpress.mdx index f043066cdcac4..55678aa94908a 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-wordpress.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-wordpress.mdx @@ -39,7 +39,7 @@ When you rebuild your WordPress site in Astro, you will notice some important di To convert a WordPress blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes). -You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#use-a-theme-or-starter-template). +You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard). diff --git a/src/content/docs/en/install-and-setup.mdx b/src/content/docs/en/install-and-setup.mdx index a199192d0876c..848856213c869 100644 --- a/src/content/docs/en/install-and-setup.mdx +++ b/src/content/docs/en/install-and-setup.mdx @@ -1,17 +1,17 @@ --- -title: Install and set up Astro +title: Install Astro sidebar: label: Installation -description: 'How to install Astro and start working in a new project.' +description: 'How to install Astro and start a new project.' i18nReady: true --- -import { CardGrid, FileTree, LinkCard, Steps } from '@astrojs/starlight/components'; +import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import ReadMore from '~/components/ReadMore.astro'; The [`create astro` CLI command](#install-from-the-cli-wizard) is the fastest way to start a new Astro project from scratch. It will walk you through every step of setting up your new Astro project and allow you to choose from a few different official starter templates. -Or, you can begin your project [using any existing theme or starter template](#use-a-theme-or-starter-template). +You can also run the CLI command with the `template` flag to begin your project using any existing theme or starter template. Explore our [themes and starters showcase](https://astro.build/themes/) where you can browse themes for blogs, portfolios, documentation sites, landing pages, and more! To install Astro manually instead, see our [step-by-step manual installation guide](#manual-setup). @@ -29,12 +29,12 @@ Prefer to try Astro in your browser? Visit [astro.new](https://astro.new/) to br Astro is built with Vite which targets browsers with modern JavaScript support by default. For a complete reference, you can see the [list of currently supported browser versions in Vite](https://vite.dev/guide/build.html#browser-compatibility). -## Start a new project +## Install from the CLI wizard -### Install from the CLI wizard +You can run `create astro` anywhere on your machine, so there's no need to create a new empty directory for your project before you begin. If you don't have an empty directory yet for your new project, the wizard will help create one for you automatically. -1. Run the following command in your terminal to start our handy install wizard: +1. Run the following command in your terminal to start the install wizard: @@ -57,201 +57,105 @@ Astro is built with Vite which targets browsers with modern JavaScript support b - You can run `create astro` anywhere on your machine, so there's no need to create a new empty directory for your project before you begin. If you don't have an empty directory yet for your new project, the wizard will help create one for you automatically. + If all goes well, you will see a success message followed by some recommended next steps. + +2. Now that your project has been created, you can `cd` into your new project directory to begin using Astro. - If all goes well, you will see a success message followed by some recommended next steps. Now that your project has been created, you can `cd` into your new project directory to begin using Astro. +3. If you skipped the "Install dependencies?" step during the CLI wizard, then be sure to install your dependencies before continuing. -2. If you skipped the "Install dependencies?" step during the CLI wizard, then be sure to install your dependencies before continuing. - -3. You can now [start the Astro dev server](#start-the-astro-dev-server) and see a live preview of your project while you build! - - -### Use a theme or starter template - -You can also start a new astro project based on an [official example](https://github.com/withastro/astro/tree/main/examples) or the `main` branch of any GitHub repository by passing a `--template` argument to the `create astro` command. - - -1. Explore our [themes and starters showcase](https://astro.build/themes/) where you can browse themes for blogs, portfolios, documentation sites, landing pages, and more! Or, [search on GitHub](https://github.com/search?o=desc&q=astro+starter&s=stars&type=Repositories) for even more starter projects. - -2. Run the following command in your terminal, substituting the official Astro starter template name, or the GitHub username and repository of the theme you want to use: - - + ```shell - # create a new project with an official example - npm create astro@latest -- --template - - # create a new project based on a GitHub repository’s main branch - npm create astro@latest -- --template / + npm install ``` ```shell - # create a new project with an official example - pnpm create astro@latest --template - - # create a new project based on a GitHub repository’s main branch - pnpm create astro@latest --template / + pnpm install ``` ```shell - # create a new project with an official example - yarn create astro --template - - # create a new project based on a GitHub repository’s main branch - yarn create astro --template / + yarn install ``` - By default, this command will use the template repository’s `main` branch. To use a different branch name, pass it as part of the `--template` argument: `/#`. - +4. You can now [start the Astro dev server](/en/develop-and-build/#start-the-astro-dev-server) and see a live preview of your project while you build! + -3. Answer the questions and follow the instructions of the CLI wizard. +## CLI installation flags -4. You can now [start the Astro dev server](#start-the-astro-dev-server) and see a live preview of your project while you make it your own! - +You can run the `create astro` command with additional flags to customize the setup process (e.g. answering "yes" to all questions, skipping the Houston animation) or your new project (e.g. install git or not, add integrations). -## Edit your project -To make changes to your project, open your project folder in your code editor. Working in development mode with the dev server running allows you to see updates to your site as you edit the code. +See [all the available `create astro` command flags](https://github.com/withastro/astro/blob/main/packages/create-astro/README.md) -You can also [customize aspects of your development environment](#configure-your-dev-environment) such as configuring TypeScript or installing the official Astro editor extensions. -### Start the Astro dev server +### Add integrations -Astro comes with a built-in development server that has everything you need for project development. The `astro dev` CLI command will start the local development server so that you can see your new website in action for the very first time. +You can start a new astro project and install any [official integrations](/en/guides/integrations-guide/) or community integrations that support the `astro add` command at the same time by passing the `--add` argument to the `create astro` command. -Every starter template comes with a pre-configured script that will run `astro dev` for you. After navigating into your project directory, use your favorite package manager to run this command and start the Astro development server. +Run the following command in your terminal, substituting any integration that supports the `astro add` command: ```shell - npm run dev + # create a new project with react and tailwind + npm create astro@latest -- --add react tailwind ``` ```shell - pnpm run dev + # create a new project with react and tailwind + pnpm create astro@latest --add react tailwind ``` ```shell - yarn run dev + # create a new project with react and tailwind + yarn create astro --add react tailwind ``` +### Use a theme or starter template -If all goes well, Astro will now be serving your project on [http://localhost:4321/](http://localhost:4321/). Visit that link in your browser and see your new site! - -### Work in development mode - -Astro will listen for live file changes in your `src/` directory and update your site preview as you build, so you will not need to restart the server as you make changes during development. You will always be able to see an up-to-date version of your site in your browser when the dev server is running. - -When viewing your site in the browser, you'll have access to the [Astro dev toolbar](/en/guides/dev-toolbar/). As you build, it will help you inspect your [islands](/en/concepts/islands/), spot accessibility issues, and more. - -If you aren't able to open your project in the browser after starting the dev server, go back to the terminal where you ran the `dev` command and check the message displayed. It should tell you if an error occurred, or if your project is being served at a different URL than [http://localhost:4321/](http://localhost:4321/). - -### Configure your dev environment - -Explore the guides below to customize your development experience. - - - - - - -### TypeScript in Astro - -Astro ships with built-in support for [TypeScript](https://www.typescriptlang.org/), which can help prevent errors at runtime by defining the shapes of objects and components in your code. - -You don't need to write TypeScript code in your Astro projects to benefit from it. Astro always treats your component code as TypeScript, and the [Astro VSCode Extension](/en/editor-setup/) will infer as much as it can to provide autocompletion, hints, and errors in your editor. - -Read more about using and configuring [TypeScript in Astro](/en/guides/typescript/) - -## Build and preview your site - -To check the version of your site that will be created at build time, quit the dev server (Ctrl + C) and run the appropriate build command for your package manager in your terminal: - - - - ```shell - npm run build - ``` - - - ```shell - pnpm build - ``` - - - ```shell - yarn run build - ``` - - - -Astro will build a deploy-ready version of your site in a separate folder (`dist/` by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production. If TypeScript is configured to `strict` or `strictest`, the `build` script will also check your project for type errors. - -When the build is finished, run the appropriate `preview` command (e.g. `npm run preview`) in your terminal and you can view the built version of your site locally in the same browser preview window. - -Note that this previews your code as it existed when the build command was last run. This is meant to give you a preview of how your site will look when it is [deployed to the web](#deploy-your-new-site). Any later changes you make to your code after building will **not** be reflected while you preview your site until you run the build command again. - -Use (Ctrl + C) to quit the preview and run another terminal command, such as restarting the dev server to go back to [working in development mode](#work-in-development-mode) which does update as you edit to show a live preview of your code changes. - -Read more about [the Astro CLI](/en/reference/cli-reference/) and the terminal commands you will use as you build with Astro. - -## Deploy your new site - -You may wish to [deploy your new site right away](/en/guides/deploy/), before you begin to add or change too much code. This is helpful to get a minimal, working version of your site published and can save you extra time and effort troubleshooting your deployment later. - -## Next Steps - -Success! You are now ready to start building with Astro! 🥳 - -Here are a few things 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. - - -### Explore Astro's Features +You can start a new astro project based on an [official example](https://github.com/withastro/astro/tree/main/examples) or the `main` branch of any GitHub repository by passing a `--template` argument to the `create astro` command. - - - - - - +Run the following command in your terminal, substituting the official Astro starter template name, or the GitHub username and repository of the theme you want to use: -### Take the introductory tutorial + + + ```shell + # create a new project with an official example + npm create astro@latest -- --template -Build a fully functional Astro blog starting from a single blank page in our [introductory tutorial](/en/tutorial/0-introduction/). + # create a new project based on a GitHub repository’s main branch + npm create astro@latest -- --template / + ``` + + + ```shell + # create a new project with an official example + pnpm create astro@latest --template + + # create a new project based on a GitHub repository’s main branch + pnpm create astro@latest --template / + ``` + + + ```shell + # create a new project with an official example + yarn create astro --template + + # create a new project based on a GitHub repository’s main branch + yarn create astro --template / + ``` + + -This is a great way to see how Astro works and walks you through the basics of pages, layouts, components, routing, islands, and more. It also includes an optional, beginner-friendly unit for those newer to web development concepts in general, which will guide you through installing the necessary applications on your computer, creating a GitHub account, and deploying your site. +By default, this command will use the template repository’s `main` branch. To use a different branch name, pass it as part of the `--template` argument: `/#`. ## Manual Setup @@ -419,6 +323,6 @@ If you prefer not to use our automatic `create astro` CLI tool, you can set up y - tsconfig.json -8. You can now [start the Astro dev server](#start-the-astro-dev-server) and see a live preview of your project while you build! +8. You can now [start the Astro dev server](/en/develop-and-build/#start-the-astro-dev-server) and see a live preview of your project while you build! - + \ No newline at end of file diff --git a/src/content/docs/en/recipes/bun.mdx b/src/content/docs/en/recipes/bun.mdx index e0ef1ee6e49cf..5a0de2ad819dc 100644 --- a/src/content/docs/en/recipes/bun.mdx +++ b/src/content/docs/en/recipes/bun.mdx @@ -26,7 +26,7 @@ bunx create-astro@latest my-astro-project-using-bun ``` :::tip -You may also [create a new Astro project from any existing Astro GitHub repository](/en/install-and-setup/#use-a-theme-or-starter-template) using the `--template` flag: +You may also [create a new Astro project from any existing Astro GitHub repository](/en/install-and-setup/#install-from-the-cli-wizard) using the `--template` flag: ```bash bunx create-astro@latest my-astro-project-using-bun --template eliancodes/brutal ``` diff --git a/src/content/docs/it/recipes/bun.mdx b/src/content/docs/it/recipes/bun.mdx index ffd084e0a5002..ede08fcb1b4c4 100644 --- a/src/content/docs/it/recipes/bun.mdx +++ b/src/content/docs/it/recipes/bun.mdx @@ -26,7 +26,7 @@ bunx create-astro@latest my-astro-project-using-bun ``` :::tip -Puoi creare anche un [nuovo progetto Astro da qualsiasi repository Astro GitHub esistente](/it/install-and-setup/#use-a-theme-or-starter-template) usando il flag `--template`: +Puoi creare anche un [nuovo progetto Astro da qualsiasi repository Astro GitHub esistente](/it/install-and-setup/#install-from-the-cli-wizard) usando il flag `--template`: ```bash bunx create-astro@latest my-astro-project-using-bun --template eliancodes/brutal ```