diff --git a/netlify.toml b/netlify.toml index 7a908490441b1..3873309825ed4 100644 --- a/netlify.toml +++ b/netlify.toml @@ -11,7 +11,11 @@ [[redirects]] from = "/en/core-concepts/component-hydration" - to = "/en/core-concepts/partial-hydration" + to = "/en/concepts/islands" + + [[redirects]] + from = "/en/core-concepts/partial-hydration" + to = "/en/concepts/islands" [[redirects]] from = "/en/guides/debugging" @@ -29,3 +33,4 @@ from = "/:lang/*" to = "/:lang/404/" status = 404 + diff --git a/public/index.css b/public/index.css index 017a715e32960..3b3ebb937c5f3 100644 --- a/public/index.css +++ b/public/index.css @@ -84,17 +84,6 @@ nav ul { margin-top: 1.25rem; } -.content > section > :is(ul, ol) > li > * + * { - margin-bottom: 1.25rem; -} - -.content > section > :is(ul, ol) > li, -.content > section > :is(ul, ol) > li > * + *, -.content > section > :is(ul, ol) > li > :is(ul, ol) > li, -.content > section > :is(ul, ol) > li > :is(ul, ol) > li > * + * { - margin-top: 0.5rem; -} - .content > section > :first-child { margin-top: 0; } diff --git a/scripts/lint-slugcheck.mjs b/scripts/lint-slugcheck.mjs index 7ee45f33da562..6e502a0aa4d30 100644 --- a/scripts/lint-slugcheck.mjs +++ b/scripts/lint-slugcheck.mjs @@ -1,6 +1,15 @@ import glob from 'fast-glob'; import kleur from 'kleur'; +/** + * Ignore these slugs, usually because the page is deprecated in English + * and no longer needs to be maintained. + **/ +const IGNORE_SLUGS = [ + // NOTE(fks, 07-11-2022): Migrated to "concepts/islands.md" + 'core-concepts/partial-hydration.md' +]; + /** Makes sure that all translations’ slugs match the English slugs. */ class SlugChecker { async run() { @@ -10,7 +19,7 @@ class SlugChecker { /** Load all Markdown pages and check non-English pages have counterparts in `pages/en/`. */ async #findMismatchedSlugs() { - const enSlugs = new Set(); + const enSlugs = new Set(IGNORE_SLUGS); /** @type {Record} */ const errorMap = {}; (await glob('./src/pages/**/*.md')) @@ -20,6 +29,7 @@ class SlugChecker { return [lang, slug]; }) .forEach(([lang, slug]) => { + console.log(enSlugs); if (enSlugs.has(slug)) return; if (!errorMap[lang]) errorMap[lang] = []; errorMap[lang].push(slug); diff --git a/src/components/IslandsDiagram.astro b/src/components/IslandsDiagram.astro index cfee264657ce9..5b1b0abdc9002 100644 --- a/src/components/IslandsDiagram.astro +++ b/src/components/IslandsDiagram.astro @@ -8,7 +8,6 @@ function slotDefault (slotName: string) {
{slotDefault('sidebarApp')}
{slotDefault('main')}
{slotDefault('carouselApp')}
-
{slotDefault('advertisement')}
{slotDefault('footer')}
@@ -19,7 +18,7 @@ function slotDefault (slotName: string) { 'header header header' 'sidebar main main' 'sidebar carousel carousel' - 'adv footer footer'; + 'footer footer footer'; grid-gap: 0.75rem; padding: 0.75rem; background: var(--theme-bg); @@ -47,12 +46,10 @@ function slotDefault (slotName: string) { } .diagram .sidebar { grid-area: sidebar; - background: hsla(210, 90%, 50%, 0.2); - border-color: hsla(210, 60%, 35%, 0.8); - color: hsl(210, 60%, 35%); } .diagram .main { grid-area: main; + height: 320px; } .diagram .carousel { grid-area: carousel; diff --git a/src/i18n/de/nav.ts b/src/i18n/de/nav.ts index 855f82687d457..a2a1d825d673a 100644 --- a/src/i18n/de/nav.ts +++ b/src/i18n/de/nav.ts @@ -12,7 +12,6 @@ export default NavDictionary({ // Core Concepts coreConcepts: 'Kernkonzepte', - 'core-concepts/partial-hydration': 'Partielle Hydratation', // Basics basics: 'Grundlagen', diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 881db9fed2717..45864b04e8880 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -13,13 +13,11 @@ export default [ { text: 'Installation', slug: 'install/auto', key: 'install' }, { text: 'Editor Setup', slug: 'editor-setup', key: 'editor-setup' }, { text: 'Migration Guide', slug: 'migrate', key: 'migrate' }, - // REMOVE "Built with Astro": (Move into astro.build) - { text: 'Built with Astro', slug: 'integrations/integrations', key: 'integrations/integrations' }, - { text: 'Astro vs. X', slug: 'comparing-astro-vs-other-tools', key: 'comparing-astro-vs-other-tools' }, { text: 'Core Concepts', header: true, type: 'learn', key: 'coreConcepts' }, - // ADD: Why Astro? - { text: 'Partial Hydration', slug: 'core-concepts/partial-hydration', key: 'core-concepts/partial-hydration' }, + { text: 'Why Astro', slug: 'concepts/why-astro', key: 'concepts/why-astro' }, + { text: 'MPA vs. SPA', slug: 'concepts/mpa-vs-spa', key: 'concepts/mpa-vs-spa' }, + { text: 'Astro Islands', slug: 'concepts/islands', key: 'concepts/islands' }, { text: 'Basics', header: true, type: 'learn', key: 'basics' }, { text: 'Project Structure', slug: 'core-concepts/project-structure', key: 'core-concepts/project-structure' }, @@ -33,7 +31,7 @@ export default [ { text: 'Deploy', slug: 'guides/deploy', key: 'guides/deploy' }, - { text: 'Features', header: true, type: 'learn', key: 'features' }, + { text: 'Guides', header: true, type: 'learn', key: 'features' }, { text: 'Configuring Astro', slug: 'guides/configuring-astro', key: 'guides/configuring-astro' }, { text: 'CSS & Styling', slug: 'guides/styling', key: 'guides/styling' }, { text: 'Data Fetching', slug: 'guides/data-fetching', key: 'guides/data-fetching' }, diff --git a/src/i18n/es/nav.ts b/src/i18n/es/nav.ts index 30c531ae4e22e..ce4c40274968f 100644 --- a/src/i18n/es/nav.ts +++ b/src/i18n/es/nav.ts @@ -13,7 +13,6 @@ export default NavDictionary({ 'core-concepts/astro-pages': 'Páginas', 'core-concepts/project-structure': 'Estructura de proyecto', 'core-concepts/routing': 'Enrutamiento', - 'core-concepts/partial-hydration': 'Hidratación parcial', 'core-concepts/framework-components': 'Componentes de framework', 'core-concepts/astro-components': 'Componentes', 'core-concepts/layouts': 'Plantillas de página', diff --git a/src/i18n/fr/nav.ts b/src/i18n/fr/nav.ts index 656884b20e782..4ef80f918af12 100644 --- a/src/i18n/fr/nav.ts +++ b/src/i18n/fr/nav.ts @@ -12,7 +12,6 @@ export default NavDictionary({ // Core Concepts coreConcepts: 'Concepts Principaux', - 'core-concepts/partial-hydration': 'Hydratation partielle', // Basics basics: 'Les Bases', diff --git a/src/i18n/ja/nav.ts b/src/i18n/ja/nav.ts index e8f4b4b332a6e..bdb29a16a72f5 100644 --- a/src/i18n/ja/nav.ts +++ b/src/i18n/ja/nav.ts @@ -11,7 +11,6 @@ export default NavDictionary({ // Core Concepts coreConcepts: 'コアコンセプト', - 'core-concepts/partial-hydration': 'パーシャルハイドレーション', // Basics basics: '基本', diff --git a/src/i18n/pt-br/nav.ts b/src/i18n/pt-br/nav.ts index bdab51d4958d1..38cb6cc4e0013 100644 --- a/src/i18n/pt-br/nav.ts +++ b/src/i18n/pt-br/nav.ts @@ -9,7 +9,6 @@ export default NavDictionary({ migrate: 'Guia de Migração', 'integrations/integrations': 'Feito com Astro', coreConcepts: 'Principais Conceitos', - 'core-concepts/partial-hydration': 'Hidratação Parcial', basics: 'Fundamentos', 'core-concepts/project-structure': 'Estrutura de Projetos', 'core-concepts/astro-components': 'Componentes', diff --git a/src/i18n/zh-cn/nav.ts b/src/i18n/zh-cn/nav.ts index a4cd59a6f6e47..a52905a3de4e3 100644 --- a/src/i18n/zh-cn/nav.ts +++ b/src/i18n/zh-cn/nav.ts @@ -9,7 +9,6 @@ export default NavDictionary({ 'integrations/integrations': '集成', 'comparing-astro-vs-other-tools': 'Astro 与其他工具比较', 'coreConcepts': '核心理念', - 'core-concepts/partial-hydration': '极简耦合', 'basics': '基础内容', 'core-concepts/project-structure': '项目结构', 'core-concepts/astro-components': '组件', diff --git a/src/pages/en/comparing-astro-vs-other-tools.md b/src/pages/en/comparing-astro-vs-other-tools.md index 38a89de70136a..1f4e4b3e6bb4d 100644 --- a/src/pages/en/comparing-astro-vs-other-tools.md +++ b/src/pages/en/comparing-astro-vs-other-tools.md @@ -11,7 +11,7 @@ This guide was written to help answer that question for several popular site bui Two key features make Astro different from most alternatives: -- [Partial hydration](/en/core-concepts/partial-hydration/) +- [Partial hydration](/en/concepts/islands/) - [Use your favorite framework(s)](/en/core-concepts/framework-components/) For more details, you can see our in-depth comparisons on this page. @@ -26,7 +26,7 @@ Docusaurus was designed to build documentation websites and has some built-in, d #### Comparing Docusaurus vs. Astro Performance -In most cases, Astro websites will load significantly faster than Docusaurus websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/core-concepts/partial-hydration/). +In most cases, Astro websites will load significantly faster than Docusaurus websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/concepts/islands/). Docusaurus doesn't support partial hydration, and instead makes the user load and rehydrate the entire page in the browser, even if most of the page content is static. This creates a slower page load and worse performance for your website. There is no way to disable this behavior in Docusaurus. @@ -45,7 +45,7 @@ Docusaurus doesn't support partial hydration, and instead makes the user load an Elder.js uses Svelte to render your website. Astro is more flexible: you are free to build UI with any popular component library (React, Preact, Vue, Svelte, Solid and others) or Astro’s HTML-like component syntax which is similar to HTML + JSX. -Elder.js is unique on this list as the only other site builder to support [partial hydration](/en/core-concepts/partial-hydration/). Both Astro and Elder.js automatically strip unnecessary JavaScript from the page, hydrating only the individual components that need it. Elder’s API for partial hydration is a bit different and Astro supports a few features that Elder.js doesn't (like `client:media`). However performance-wise, both projects will build very similar sites. +Elder.js is unique on this list as the only other site builder to support [partial hydration](/en/concepts/islands/). Both Astro and Elder.js automatically strip unnecessary JavaScript from the page, hydrating only the individual components that need it. Elder’s API for partial hydration is a bit different and Astro supports a few features that Elder.js doesn't (like `client:media`). However performance-wise, both projects will build very similar sites. Elder.js uses a custom routing solution that may feel unfamiliar to new developers. Astro uses [file-based routing](/en/core-concepts/routing/) which should feel familiar to anyone coming from Next.js, SvelteKit, and even other static site builders like Eleventy. @@ -65,7 +65,7 @@ Conceptually, Eleventy is aligned with Astro’s "minimal client-side JavaScript Eleventy achieves this by pushing you to avoid JavaScript entirely. Eleventy sites are often written with little to no JavaScript at all. This becomes an issue when you do need client-side JavaScript. It is up to you to create your own asset build pipeline for Eleventy. This can be time consuming and forces you to set up bundling, minification, and other complex optimizations yourself. -By contrast, Astro automatically builds your client-side JavaScript & CSS for you. Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/core-concepts/partial-hydration/). While it is possible to achieve this yourself in Eleventy, Astro offers it built-in by default. +By contrast, Astro automatically builds your client-side JavaScript & CSS for you. Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/concepts/islands/). While it is possible to achieve this yourself in Eleventy, Astro offers it built-in by default. #### Case Study: Building a Documentation Website @@ -86,7 +86,7 @@ Gatsby requires a custom GraphQL API for working with all of your site content. #### Comparing Gatsby vs. Astro Performance -In most cases, Astro websites will load significantly faster than Gatsby websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/core-concepts/partial-hydration/). +In most cases, Astro websites will load significantly faster than Gatsby websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/concepts/islands/). Gatsby doesn't support partial hydration, and instead makes the user load and rehydrate the entire page in the browser, even if most of the page content is static. This creates a slower page load and worse performance for your website. Gatsby has [a community plugin](https://www.gatsbyjs.com/plugins/gatsby-plugin-no-javascript/) for removing all JavaScript from the page, but this would break many websites. This leaves you with an all-or-nothing decision for interactivity on each page. @@ -111,7 +111,7 @@ Hugo uses a custom [templating language](https://gohugo.io/templates/introductio Conceptually, Hugo is aligned with Astro’s "minimal client-side JavaScript" approach to web development. Hugo and Astro both offer similar, zero-JavaScript-by-default performance baselines. -Both Hugo and Astro offers built-in support for building, bundling and minifying JavaScript. Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/core-concepts/partial-hydration/). While it is possible to achieve this yourself in Hugo, Astro offers it built-in by default. +Both Hugo and Astro offers built-in support for building, bundling and minifying JavaScript. Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/concepts/islands/). While it is possible to achieve this yourself in Hugo, Astro offers it built-in by default. #### Case Study: Building a Documentation Website @@ -154,7 +154,7 @@ SvelteKit supports both Static Site Generation (SSG) and Server-Side Rendering ( #### Comparing SvelteKit vs. Astro Performance -In most cases, Astro websites will load faster than SvelteKit websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/core-concepts/partial-hydration/). +In most cases, Astro websites will load faster than SvelteKit websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/concepts/islands/). SvelteKit doesn't support partial hydration, and instead makes the user load and rehydrate the entire page in the browser, even if most of the page content is static. This creates a slower page load and worse performance for your website. SvelteKit does offer support for [page-level static, zero-JavaScript pages](https://kit.svelte.dev/docs#ssr-and-javascript-hydrate). However, there is no planned support for hydrating individual components on the page. This leaves you with an all-or-nothing decision for interactivity on each page. @@ -181,7 +181,7 @@ Next.js supports both Static Site Generation (SSG) and Server-Side Rendering (SS #### Comparing Next.js vs. Astro Performance -In most cases, Astro websites will load significantly faster than Next.js websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/core-concepts/partial-hydration/). +In most cases, Astro websites will load significantly faster than Next.js websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/concepts/islands/). Next.js doesn't support partial hydration, and instead makes the user load and rehydrate the entire page in the browser, even if most of the page content is static. This creates a slower page load and worse performance for your website. Next.js has [experimental support](https://piccalil.li/blog/new-year-new-website/#heading-no-client-side-react-code) for fully-static, zero-JavaScript pages. However, there is no planned support for hydrating individual components on the page. This leaves you with an all-or-nothing decision for interactivity on each page. @@ -208,7 +208,7 @@ Nuxt supports both Static Site Generation (SSG) and Server-Side Rendering (SSR). #### Comparing Nuxt vs. Astro Performance -In most cases, Astro websites will load significantly faster than Nuxt websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/core-concepts/partial-hydration/). +In most cases, Astro websites will load significantly faster than Nuxt websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/concepts/islands/). Nuxt doesn't support partial hydration, and instead makes the user load and rehydrate the entire page in the browser, even if most of the page content is static. This creates a slower page load and worse performance for your website. There is no way to disable this behavior in Nuxt. @@ -248,7 +248,7 @@ Evan You (creator of Vue.js) is currently working on a new version of Vuepress c #### Comparing VuePress vs. Astro Performance -In most cases, Astro websites will load significantly faster than VuePress websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/core-concepts/partial-hydration/). +In most cases, Astro websites will load significantly faster than VuePress websites. This is because Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/concepts/islands/). VuePress doesn't support partial hydration, and instead makes the user load and rehydrate the entire page in the browser, even if most of the page content is static. This creates a slower page load and worse performance for your website. There is no way to disable this behavior in VuePress. @@ -271,7 +271,7 @@ Zola uses [Tera](https://tera.netlify.app/) to render your website. Astro lets y Conceptually, Zola is aligned with Astro’s "minimal client-side JavaScript" approach to web development. Zola and Astro both offer similar, zero-JavaScript-by-default performance baselines. -Astro offers built-in support for building, bundling and minifying JavaScript. Zola requires using another build tool like Webpack to bundle and process JavaScript. Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/core-concepts/partial-hydration/). While it is possible to achieve this yourself in Zola, Astro offers it built-in by default. +Astro offers built-in support for building, bundling and minifying JavaScript. Zola requires using another build tool like Webpack to bundle and process JavaScript. Astro automatically strips unnecessary JavaScript from the page, hydrating only the individual components that need it. This feature is called [partial hydration](/en/concepts/islands/). While it is possible to achieve this yourself in Zola, Astro offers it built-in by default. #### Case Study: Building a Documentation Website diff --git a/src/pages/en/concepts/islands.md b/src/pages/en/concepts/islands.md new file mode 100644 index 0000000000000..1ae026c7694ac --- /dev/null +++ b/src/pages/en/concepts/islands.md @@ -0,0 +1,67 @@ +--- +layout: ~/layouts/MainLayout.astro +title: Astro Islands +description: "Astro Islands (aka Component Islands) are a pattern of web architecture pioneered by Astro. The term was first coined by Etsy's frontend architect Katie Sylor-Miller in 2019, and expanded on by Preact creator Jason Miller." +i18nReady: true +setup: | + import IslandsDiagram from '~/components/IslandsDiagram.astro'; +--- + +**Astro Islands** (aka Component Islands) are a pattern of web architecture pioneered by Astro. The term was first coined by Etsy's frontend architect [Katie Sylor-Miller](https://twitter.com/ksylor) in 2019, and expanded on in [this post](https://jasonformat.com/islands-architecture/) by Preact creator Jason Miller. + +## What is an Astro Island? + +The term "Astro Island" refers to an interactive UI component on an otherwise static page of HTML. Multiple islands can exist on a page, and an island always renders in isolation. Think of them as islands in a sea of static, non-interactive HTML. + + + Header (interactive island) + Sidebar (static HTML) + + Static content like text, images, etc. + + Image carousel (interactive island) + Footer (static HTML) + + +In Astro, you can use any supported UI framework (React, Svelte, Vue, etc.) to render islands in the browser. You can mix and match different frameworks on the same page, or just pick your favorite. + +The technique that this architectural pattern builds on is known as **partial** or **selective hydration.** Astro leverages this technique behind the scenes, powering your islands automatically. + +## How Do Islands Work in Astro? + +**Astro generates every website with zero client-side JavaScript, by default.** Use a frontend UI component built with [React](https://reactjs.org/), [Preact](https://preactjs.com/), [Svelte](https://svelte.dev/), [Vue](https://vuejs.org/), [SolidJS](https://www.solidjs.com/), [AlpineJS](https://alpinejs.dev/), or [Lit](https://lit.dev/) and Astro will automatically render it to HTML ahead-of-time and then strip out all of the JavaScript. This keeps every site fast by default by removing all unused JavaScript from the page. + +```astro +--- +// Example: Use a static React component on the page, without JavaScript. +import MyReactComponent from '../components/MyReactComponent.jsx'; +--- + + +``` + +But sometimes, client-side JavaScript is required for creating interactive UI. Instead of forcing your entire page to become an SPA-like JavaScript application, Astro asks you to create an island. + +```astro +--- +// Example: Use a dynamic React component on the page. +import MyReactComponent from '../components/MyReactComponent.jsx'; +--- + + +``` + +With Astro Islands, the vast majority of your site remains pure, lightweight HTML and CSS. In the example above, you have just added a single, isolated **island of interactivity** without also changing the rest of the page. + +## What are the benefits of Islands? + +The most obvious benefit to building with Astro Islands is performance: the majority of your website is converted to fast, static HTML and JavaScript is only loaded for the individual components that need it. JavaScript is one of the slowest assets that you can load per-byte, so every byte counts. + +Another benefit is parallel loading. In the example illustration above, the low-priority "image carousel" island doesn't need to block the high-priority "header" island. The two load in parallel and hydrate in isolation, meaning that the header becomes interactive immediately without having to wait for the heavier carousel lower down the page. + +Even better, you can tell Astro exactly how and when to render each component. If that image carousel is really expensive to load, you can attach a special [client directive](/en/reference/directives-reference/#client-directives) that tells Astro to only load the carousel when it becomes visible on the page. If the user never sees it, it never loads. + +In Astro, it’s up to you as the developer to explicitly tell Astro which components on the page need to also run in the browser. Astro will only hydrate exactly what’s needed on the page and leave the rest of your site as static HTML. + +**Islands are the secret to Astro’s fast-by-default performance story!** diff --git a/src/pages/en/concepts/mpa-vs-spa.md b/src/pages/en/concepts/mpa-vs-spa.md new file mode 100644 index 0000000000000..48dc57e683b01 --- /dev/null +++ b/src/pages/en/concepts/mpa-vs-spa.md @@ -0,0 +1,71 @@ +--- +layout: ~/layouts/MainLayout.astro +title: MPAs vs. SPAs +description: "Understanding the tradeoffs between Multi-Page Application (MPA) and Single-Page Application (SPA) architecture is key to understanding what makes Astro different from other web frameworks." +i18nReady: true +--- + +Understanding the tradeoffs between Multi-Page Application (MPA) and Single-Page Application (SPA) architecture is key to understanding what makes Astro different from other web frameworks like Next.js and Remix. + +## Terminology + +**A Multi-Page Application (MPA)** is a website consisting of multiple HTML pages, mostly rendered on a server. When you navigate to a new page, your browser requests a new page of HTML from the server. **Astro is an MPA framework.** Traditional MPA frameworks also include Ruby on Rails, Python Django, PHP Laravel, Wordpress, and static site builders like Eleventy or Hugo. + +**A Single-Page Application (SPA)** is a website consisting of a single JavaScript application that loads in the user's browser and then renders HTML locally. SPAs may *also* generate HTML on the server, but SPAs are unique in their ability to run your website as a JavaScript application in the browser to render a new page of HTML when you navigate. Next.js, Nuxt, SvelteKit, Remix, Gatsby, and Create React App are all examples of SPA frameworks. + +## Astro vs. other MPAs + +Astro is an MPA framework. However, Astro is also unique from other MPA frameworks. Its main difference is that it uses of JavaScript as its server language and runtime. Traditional MPA frameworks would have you write a different language on the server (Ruby, PHP, etc.) and JavaScript on the browser. In Astro, you're always just writing JavaScript, HTML and CSS. That way, you can render your UI components (like React and Svelte) on both the server and the client. + +The result is a developer experience that feels a lot like Next.js and other modern web frameworks, but with performance characteristics of a more traditional MPA site architecture. + +## MPAs vs. SPAs + +There are three main differences to be aware of when comparing MPAs vs. SPAs: + +#### Server rendering (MPA) vs. client rendering (SPA) + +In MPAs, most of your page's HTML is rendered on the server. In SPAs, most HTML is rendered locally by running JavaScript in the browser. This has a dramatic impact on site behavior, performance, and SEO. + +Rendering your HTML in the browser may sound like the faster option vs. requesting it from a remote server. However, the opposite is true. An SPA will consistently perform slower on first page load vs. an MPA, unless server rendering is used. This is because an SPA needs to download, parse, and run an entire JavaScript application in the browser just to render any HTML on the page. Then, your SPA will likely need to fetch remote data anyway, introducing even more wait time before your page is finished loading. + +Most SPA frameworks will attempt to mitigate this performance problem by adding basic server rendering on the first page load. This is an improvement, but it introduces new complexity due to the fact that your website can now render in multiple ways and in multiple environments (server, browser). This also introduces a new "uncanny valley" problem where your site appears loaded (HTML) but is unresponsive since the application JavaScript logic is still loading in the background. + +MPAs render all HTML on a remote server and often don't require much (if any) JavaScript to run. This gives MPAs a much faster first load experience than SPAs, which is essential for content-focused websites. But this comes with a tradeoff: future page navigation can't benefit from local rendering, so long-lived user experiences won't benefit as much after the first page load. + + +#### Server routing (MPA) vs. client routing (SPA) + +Where does your website router live? In an MPA, every request to the server decides which HTML to respond with, so the routing logic lives in the server. In a SPA, your router locally runs in the browser and hijacks any navigation to render the new page without ever hitting a server. + +This is a similar tradeoff to the one described above: MPAs offer a faster first load experience, while SPAs may offer a faster second or third page load once the JavaScript application is fully loaded in the browser. + +SPAs can also offer more powerful transitions across page navigation because they control so much about page rendering. To match this support, MPAs leverage tools like Hotwire's [Turbo](https://turbo.hotwired.dev/) that mimic client routing by also controlling navigation in the browser. The HTML is still rendered on the server, but Turbo can now display a seamless transition between pages similar to client routing in an SPA. + +#### Server state management (MPA) vs. client state management (SPA) + +SPAs are the superior architecture for websites that deal with complex, multi-page state management (think: Gmail). This is because an SPA runs the entire website as a single JavaScript application, which lets the application maintain state and memory across multiple pages. Interactive, data-driven experiences like inboxes and admin dashboards do well as SPAs because the website itself is inherently "app-like". + + +## Are MPAs Better than SPAs? + +When comparing MPAs vs SPAs, there is no "better" or "worse" choice. It all comes down to tradeoffs. + +**Astro prioritizes the performance and simplicity of MPAs because it makes the most sense for our usecase of content-focused websites.** More stateful, interaction-heavy websites may benefit more from the app-like architecture that SPAs bring at the expense of first-load performance. + + +## Case Studies + +Below are all of the public Astro comparisons that we are aware of: + +- [Astro vs. SPA (Next.js)](https://twitter.com/t3dotgg/status/1437195415439360003) - 94% less JavaScript +- [Astro vs. SPA (Next.js)](https://twitter.com/jlengstorf/status/1442707241627385860?lang=en) - 34% faster load +- [Astro vs. SPA (Remix, SvelteKit)](https://www.youtube.com/watch?v=2ZEMb_H-LYE&t=8163s) - "That [Lighthouse score] is incredible." +- [Astro vs. Qwik](https://www.youtube.com/watch?v=2ZEMb_H-LYE&t=8504s) - 43% faster TTI + +If you know a public migration or benchmark and don't see it listed here, please create a PR to add it. +## More Resources + +If you'd like to learn more, Surma (Google) and Jake Archibald (Google) recorded a great back-and-forth discussion [on this exact topic.](https://www.youtube.com/watch?v=ivLhf3hq7eM) + + diff --git a/src/pages/en/concepts/why-astro.md b/src/pages/en/concepts/why-astro.md new file mode 100644 index 0000000000000..a4b86b94618fd --- /dev/null +++ b/src/pages/en/concepts/why-astro.md @@ -0,0 +1,102 @@ +--- +layout: ~/layouts/MainLayout.astro +title: Why Astro? +description: "Astro is an all-in-one web framework for building fast, content-focused websites. Learn more." +i18nReady: true +--- + +Astro is an **all-in-one** **web framework** for building **fast,** **content-focused websites.** + +Why choose Astro over another web framework? Here are five core design principles to help explain why we built Astro, the problems that it exists to solve, and why Astro may be the best choice for your project or team. + +#### Astro is... + +1. [Content-focused](#): Astro was designed for content-rich websites. +2. [Server-first](#): Websites run faster when they render HTML on the server. +3. [Fast by default](#): It should be impossible to build a slow website in Astro. +4. [Easy to use](#): You don't need to be an expert to build something with Astro. +5. [Fully-featured, but flexible](#): Over 100+ Astro integrations to choose from. + +## Content-focused + +**Astro was designed for building content-rich websites.** This includes most marketing sites, publishing sites, documentation sites, blogs, portfolios, and some ecommerce sites. + +By contrast, most modern web frameworks are designed for building *web applications*. These frameworks work best for building more complex, application-like experiences in the browser: logged-in admin dashboards, inboxes, social networks, todo lists, and even native-like applications like [Figma](https://figma.com/) and [Ping](https://ping.gg/). + +This is one of the most important differences to understand about Astro. Astro's unique focus on content lets Astro make tradeoffs and deliver unmatched performance features that wouldn't make sense for more application-focused web frameworks to implement. + +:::tip +If your project falls into the second "application" camp, Astro might not be the right choice for your project... **and that's okay!** Check out [Next.js](https://nextjs.org/) for a great application-focused web framework alternative. +::: + + + + +## Server-first + +**Astro leverages server-side rendering over client-side rendering as much as possible.** This is the same approach that traditional server-side frameworks -- PHP, WordPress, Laravel, Ruby on Rails, etc. -- have been using for decades. But you don't need to learn a second server-side language to unlock it. With Astro, everything is still just HTML, CSS, and JavaScript (or TypeScript, if you prefer). + +This approach stands in contrast to other modern JavaScript web frameworks like Next.js, SvelteKit, Nuxt, Remix, and others. These frameworks require client-side rendering of your entire website and include server-side rendering mainly to address performance concerns. This approach has been dubbed the **Single Page App (SPA)**, in contrast with Astro's **Multi Page App (MPA)** approach. + +The SPA model has its benefits. However, these come at the expense of additional complexity and performance tradeoffs. These tradeoffs harm page performance -- including critical metrics like [Time to Interactive (TTI)](https://web.dev/interactive/) -- which doesn't make much sense for content-focused websites where first-load performance is essential. + +📚 [Learn more about what makes Astro's MPA architecture unique.](/en/concepts/mpa-vs-spa/) + + +## Fast by default + +Good performance is always important, but it is *especially* critical for content-focused websites. It has been well-proven that poor performance loses you engagement, conversions, and money. For example: + +- Every 100ms faster → 1% more conversions ([Mobify](https://web.dev/why-speed-matters/), earning +$380,000/yr) +- 50% faster → 12% more sales ([AutoAnything](https://www.digitalcommerce360.com/2010/08/19/web-accelerator-revs-conversion-and-sales-autoanything/)) +- 20% faster → 10% more conversions ([Furniture Village](https://www.thinkwithgoogle.com/intl/en-gb/marketing-strategies/app-and-mobile/furniture-village-and-greenlight-slash-page-load-times-boosting-user-experience/)) +- 40% faster → 15% more sign-ups ([Pinterest](https://medium.com/pinterest-engineering/driving-user-growth-with-performance-improvements-cfc50dafadd7)) +- 850ms faster → 7% more conversions ([COOK](https://web.dev/why-speed-matters/)) +- 1 seconds slowness → 10% less users ([BBC](https://www.creativebloq.com/features/how-the-bbc-builds-websites-that-scale)) + +In many web frameworks, it is easy to build a website that looks great during development only to load painfully slow once deployed. JavaScript is often the culprit, since users phones and lower-powered devices rarely match the speed of a developer's laptop. + +Astro's magic is in how it combines the two values explained above -- a content focus with a server-first MPA architecture -- to make tradeoffs and deliver features that other frameworks cannot. The result is amazing web performance for every website, out of the box. Our goal: **It should be nearly impossible to build a slow website with Astro.** + +An Astro website can [load 40% faster with 90% less JavaScript](https://twitter.com/t3dotgg/status/1437195415439360003) than the same site built with the most popular React web framework. But don't take our word for it: watch Astro's performance leave Ryan Carniato (creator of Solid.js and Marko) [speechless](https://youtu.be/2ZEMb_H-LYE?t=8163). + + +## Easy to use + +**Astro's goal is to be accessible to every web developer.** Astro was designed to feel familiar and approachable regardless of skill level or past experience with web development. + +We started by making sure that you could use any favorite UI component languages that you already know. React, Preact, Svelte, Vue, Solid, Lit, and several others are all supported for creating new UI components in an Astro project. + +We also wanted to make sure that Astro had a great built-in component language as well. To do that, we created our own `.astro` UI language. It's heavily influenced by HTML: any valid snippet of HTML is already a valid Astro component! But it also combines some of our favorite features borrowed from other component languages like JSX expressions (React) and CSS scoping by default (Svelte and Vue). + +Astro was designed to be less complex than other UI frameworks and languages. One big reason for this is that Astro was designed to render on the server, not in the browser. That means that you don't need to worry about: hooks (React), stale closures (also React), refs (Vue), observables (Svelte), atoms, selectors, reactions, or derivations. There is no reactivity on the server, so all of that complexity melts away. + +One of our favorite sayings is: **opt-in to complexity.** We designed Astro to remove as much "required complexity" as possible from the developer experience, especially as you onboard for the first time. You can build a "Hello World" example website in Astro with just HTML and CSS. Then, when you need to build something more powerful, you can incrementally reach for new features and APIs as you go. + + +## Fully-featured, but flexible + +**Astro is an all-in-one web framework that comes with everything you need to build a website.** Astro includes a component syntax, file-based routing, asset handling, a build process, bundling, optimizations, data-fetching, and more. You can build great websites without ever reaching outside of Astro's core feature set. + +If you need more control, you can extend Astro with over [100+ integrations](https://astro.build/integrations/) like [React](https://www.npmjs.com/package/@astrojs/react), [Svelte](https://www.npmjs.com/package/@astrojs/svelte), [Vue](https://www.npmjs.com/package/@astrojs/vue), [Tailwind CSS](https://www.npmjs.com/package/@astrojs/tailwind), [MDX](https://www.npmjs.com/package/@astrojs/mdx), [image optimizations](https://www.npmjs.com/package/@astrojs/images), and more. [Connect your favorite CMS](https://astro.build/integrations/) or [deploy to your favorite host](/en/guides/deploy/) with just a single command. + +Astro is UI-agnostic, meaning you can **Bring Your Own UI Framework (BYOF)**. React, Preact, Solid, Svelte, Vue, and Lit are all officially supported in Astro. You can even mix and match different frameworks on the same page, making future migrations easier and preventing project lock-in to a single framework. + + + + + + + + + + + + + + + + + + + diff --git a/src/pages/en/core-concepts/partial-hydration.astro b/src/pages/en/core-concepts/partial-hydration.astro new file mode 100644 index 0000000000000..745ce97a95851 --- /dev/null +++ b/src/pages/en/core-concepts/partial-hydration.astro @@ -0,0 +1 @@ + diff --git a/src/pages/en/core-concepts/partial-hydration.md b/src/pages/en/core-concepts/partial-hydration.md deleted file mode 100644 index 0edbc0cd350d0..0000000000000 --- a/src/pages/en/core-concepts/partial-hydration.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -layout: ~/layouts/MainLayout.astro -title: Partial Hydration in Astro -description: Learn how partial hydration works using "Islands Architecture" in Astro. -setup: | - import IslandsDiagram from '~/components/IslandsDiagram.astro'; -i18nReady: true ---- - -**Astro generates every website with zero client-side JavaScript, by default.** Use a frontend UI component built with [React](https://reactjs.org/), [Preact](https://preactjs.com/), [Svelte](https://svelte.dev/), [Vue](https://vuejs.org/), [SolidJS](https://www.solidjs.com/), [AlpineJS](https://alpinejs.dev/) or [Lit](https://lit.dev/) and Astro will automatically render it to HTML at build-time and strip away all JavaScript. This keeps every site fast by default. - -```astro ---- -// Example: Use a static React component on the page, without JavaScript. -import MyReactComponent from '../components/MyReactComponent.jsx'; ---- - - -``` - -But sometimes, client-side JavaScript is required for creating interactive UIs. When you find yourself needing interactive UI on the page, Astro doesn't force you to go 100% JavaScript on the entire page. Instead, Astro uses a technique called **partial hydration** that lets you hydrate individual components on the page. This way, you only send down the absolutely essential JavaScript that you need to run your page. - -```astro ---- -// Example: Use a dynamic React component on the page. -import MyReactComponent from '../components/MyReactComponent.jsx'; ---- - - -``` - -The vast majority of your site remains pure, lightweight HTML and CSS, with isolated **islands of interactivity.** - - -## Partial Hydration - -There are plenty of cases where you need an interactive UI component to run in the browser: - -- An image carousel -- An auto-complete search bar -- A mobile sidebar open/close button -- A "Buy Now" button - -In Astro, it’s up to you as the developer to explicitly opt in any components on the page that need to run in the browser. Astro will only hydrate exactly what’s needed on the page and leave the rest of your site as static HTML. This technique is known as **partial hydration**. - -**Partial hydration is the secret to Astro’s fast-by-default performance story.** - -## Islands Architecture - -**Islands architecture** is the idea of using partial hydration to build entire websites. Islands architecture is an alternative to the common process of building your website into a client-side JavaScript bundle that must be shipped to the user. - -> The general idea of an “Islands” architecture is deceptively simple: render HTML pages on the server, and inject placeholders or slots around highly dynamic regions. ->
-- [Islands Architecture: Jason Miller](https://jasonformat.com/islands-architecture/) - -Besides the obvious performance benefits of sending less JavaScript down to the browser, there are two key benefits to islands architecture: - -- **Components load individually.** A lightweight component (like a sidebar toggle) will load and render quickly without being blocked by the heavier components on the page. -- **Components render in isolation.** Each part of the page is an isolated unit, and a performance issue in one unit won't directly affect the others. - - - Header "app" - Sidebar "app" - - Server-rendered HTML content like text, images, etc. - - Image carousel "app" - Advertisement
(server-rendered) - Footer (server-rendered HTML) - - -_Source: [Islands Architecture: Jason Miller](https://jasonformat.com/islands-architecture/)_ diff --git a/src/pages/en/core-concepts/sharing-state.md b/src/pages/en/core-concepts/sharing-state.md index 3923b1d86b735..e184c28a0c1f5 100644 --- a/src/pages/en/core-concepts/sharing-state.md +++ b/src/pages/en/core-concepts/sharing-state.md @@ -8,7 +8,7 @@ setup: | import LoopingVideo from '~/components/LoopingVideo.astro' --- -When building an Astro website with [islands architecture / partial hydration](/en/core-concepts/partial-hydration/), you may have run into this problem: **I want to share state between my components.** +When building an Astro website with [islands architecture / partial hydration](/en/concepts/islands/), you may have run into this problem: **I want to share state between my components.** UI frameworks like React or Vue may encourage ["context" providers](https://reactjs.org/docs/context.html) for other components to consume. But when [partially hydrating components](/en/core-concepts/framework-components/#hydrating-interactive-components) within Astro or Markdown, you can't use these context wrappers. diff --git a/src/pages/en/getting-started.md b/src/pages/en/getting-started.md index dac927c4494f2..637d73a3a4426 100644 --- a/src/pages/en/getting-started.md +++ b/src/pages/en/getting-started.md @@ -7,32 +7,40 @@ title: Getting Started description: A basic intro to Astro. i18nReady: true --- -Static Site Generator 🚀 Bring your own Framework 🚀 Ship Less JavaScript -:::tip -Have an older project? Follow the [migration guide](/en/migrate/) to upgrade to the v1.0 beta! -::: +#### What is Astro? -## Try Astro +Astro is an **all-in-one** **web framework** for building **fast,** **content-focused** websites. -We've made it as easy as possible to get started with Astro either in your browser, or on your machine! +#### Key Features -### Online Playgrounds +- **Component Islands:** A new web architecture for building faster websites. +- **Server-first API design:** Move expensive hydration off of your users' devices. +- **Zero JS, by default:** No JavaScript runtime overhead to slow you down. +- **Edge-ready:** Deploy anywhere, even a global edge runtime like Deno or Cloudflare. +- **Customizable:** Tailwind, MDX, and 100+ other integrations to choose from. +- **UI-agnostic:** Supports React, Preact, Svelte, Vue, Solid, Lit and more. -Visit [astro.new](https://astro.new/) for the easiest way to "try before you buy." Choose from a variety of starter templates and start building a full, working version of Astro right in your browser! + + + + -Or, **instantly launch our basic starter project** with just one click of a button: +Check out our detailed [Why Astro](/en/concepts/why-astro/) breakdown to learn more about what makes Astro special. ✨ + + +## Try Astro in your browser + +Visit [astro.new](https://astro.new/) and choose from a variety of templates to get started. Play around with a full, working version of Astro right in your browser!
- - + +
-### Install Astro Locally - -Ready to install? +## Start your first project -Get a new project up and running locally in no time with our easy `create-astro` CLI wizard! +Get a new Astro project up and running locally with our helpful `create-astro` CLI wizard! ```bash # create a new project with npm @@ -45,22 +53,8 @@ yarn create astro pnpm create astro@latest ``` -⚙️ Our [Installation Guide](/en/install/auto/) has full, step-by-step instructions for installing Astro with your favourite package manager. - -⚙️ See instructions for [manual setup](/en/install/manual/) instead. - - -## Start building with Astro +Our [Installation Guide](/en/install/auto/) has full, step-by-step instructions for installing Astro using your favorite package manager. -Jump right in and add some content and features to your site! - -🏗️ Add new [Astro (.astro) pages](/en/core-concepts/astro-pages/) and/or [Markdown (.md) pages](/en/guides/markdown-content/) to your site. - -🏗️ Create your first [Layout](/en/core-concepts/layouts/). - -🏗️ Add additional [CSS and styling](/en/guides/styling/) to your site. - -*... check out even more under **Features*** @@ -68,13 +62,13 @@ Jump right in and add some content and features to your site! See examples of some of the key concepts and patterns of an Astro site! -📚 Read more about Astro’s [project structure](/en/core-concepts/project-structure/). +📚 [Add your first page](/en/core-concepts/astro-pages/) to your site. -📚 Learn about Astro's [template directives](/en/reference/directives-reference/). +📚 Read more about Astro’s [project structure](/en/core-concepts/project-structure/). -📚 Explore Astro’s [runtime API](/en/reference/api-reference/). +📚 Learn about Astro's [file-based routing](/en/core-concepts/routing/). -*... find more material under **Reference*** +*... find our full API documentation under the **Reference** tab.* ## Extend Astro @@ -85,7 +79,7 @@ See examples of some of the key concepts and patterns of an Astro site! 🧰 Get inspired by visiting our [site showcase](https://astro.build/showcase/). -*... see our [guide to using integrations](/en/guides/integrations-guide/)* +*... see our [guide to using integrations](/en/guides/integrations-guide/)*. diff --git a/src/pages/en/migration/0.21.0.astro b/src/pages/en/migration/0.21.0.astro index efedd1829bce9..c0747ce4ee741 100644 --- a/src/pages/en/migration/0.21.0.astro +++ b/src/pages/en/migration/0.21.0.astro @@ -1 +1 @@ - +