From 867c6cc6c86324b254bd64a30f4624329907dd40 Mon Sep 17 00:00:00 2001 From: "Fred K. Schott" Date: Mon, 11 Jul 2022 15:35:35 -0700 Subject: [PATCH 1/7] add new core concepts --- netlify.toml | 5 + public/index.css | 11 -- src/components/IslandsDiagram.astro | 7 +- src/i18n/en/nav.ts | 10 +- src/pages/en/concepts/islands.md | 67 ++++++++ src/pages/en/concepts/mpa-vs-spa.md | 90 +++++++++++ src/pages/en/concepts/why-astro.md | 150 ++++++++++++++++++ .../en/core-concepts/partial-hydration.md | 72 --------- src/pages/en/getting-started.md | 58 +++---- 9 files changed, 344 insertions(+), 126 deletions(-) create mode 100644 src/pages/en/concepts/islands.md create mode 100644 src/pages/en/concepts/mpa-vs-spa.md create mode 100644 src/pages/en/concepts/why-astro.md delete mode 100644 src/pages/en/core-concepts/partial-hydration.md diff --git a/netlify.toml b/netlify.toml index 7a908490441b1..4bd187b4232ee 100644 --- a/netlify.toml +++ b/netlify.toml @@ -29,3 +29,8 @@ from = "/:lang/*" to = "/:lang/404/" status = 404 + + [[redirects]] + from = "/en/core-concepts/partial-hydration" + to = "/en/concepts/islands-architecture" + 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/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/en/nav.ts b/src/i18n/en/nav.ts index 881db9fed2717..8f6e98563acca 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: 'Component 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/pages/en/concepts/islands.md b/src/pages/en/concepts/islands.md new file mode 100644 index 0000000000000..05c05a2c4a2c3 --- /dev/null +++ b/src/pages/en/concepts/islands.md @@ -0,0 +1,67 @@ +--- +layout: ~/layouts/MainLayout.astro +title: Component Islands +description: TODO +i18nReady: true +setup: | + import IslandsDiagram from '~/components/IslandsDiagram.astro'; +--- + +**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 a Component Island? + +Component Island (or just "Island" for short) 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) + + +You can use any 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 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. Astro doesn't force you to go 100% JavaScript to render the entire page. Instead, Astro will have you create an island. + +```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. All you've added is a single, isolated **island of interactivity.** + +## What are the benefits of Islands? + +The most obvious benefit to islands architecture 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 non-blocking loading. In the example illustration above, the low-priority "image carosel" island doesn't 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 carosel lower down the page. + +Even better, you can tell Astro exactly how and when to render each component. If that image carosel is really expensive to load, you can attach an special **client-directive** that tells Astro to only load the carosel 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 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. + +**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..d511ee0ad1a9e --- /dev/null +++ b/src/pages/en/concepts/mpa-vs-spa.md @@ -0,0 +1,90 @@ +--- +layout: ~/layouts/MainLayout.astro +title: MPAs vs. SPAs +description: TODO +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.** More traditional MPA frameworks also include Ruby on Rails, Python Django, PHP Laravel, Wordpress, and static site builders like Eleventy, Hugo and VitePress. + +**A Single-Page Application (SPA)** is a website consisting of a JavaScript application that loads in the user's browser and then renders HTML locally. SPAs may *also* generate HTML on the server (especially for the the first page load) but SPAs are unique in their ability to render HTML locally when you navigate to a new page. 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 unique from other MPA frameworks due to its use of JavaScript as a server runtime. Traditional MPA frameworks would have you write one language on the server (Ruby, PHP, etc.) and JavaScript on the browser. In Astro, you're always writing JavaScript. You can also re-use UI components (like React and Svelte) on both the server and the client. + +The result is that Astro has a developer experience similar to that of Next.js or another modern SPA, even if the user experience is an entirely different 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 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, a true SPAs (with no server rendering) will be consistently slower than an MPA. This is because an SPA has 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. Server rendering the first page gives your user something to look at while your site loads in the background. However, this can introduce a new "uncanny valley" problem where your site appears loaded but unresponsive, since the application logic is still loading in the background. + +MPAs render all HTML on a remote server and often don't require much 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 may feel slower in MPAs vs. SPAs. + + +#### 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 an SPA, your router runs right in the browser, and hijacks any navigation to render the new page locally without ever hitting a server. + +This is a similar tradeoff to the one described above: MPAs offer a faster first load experience, while SPAs sometimes ofer a faster second or third page load once the JavaScript application is fully loaded in the browser. + +SPAs can also offer a more seamless navigation experience because they control rendering across the entire transition. To mitigate this, 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 model for complex state management. Because the entire website runs as a single JavaScript application in the browser, SPAs don't need to worry about maintaining state across page transitions. Both MPAs and most SPAs need to worry about server-side state for server rendering. + +SPAs really shine in complex websites that display lots of interactive data and need lots of JavaScript to run. Interactive, data-drive experiences like inboxes and admin dashboards do well as SPAs because the website itself is inherintely "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 from the app-like behavior that SPAs bring at the expense of 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) + + + + + + + + \ No newline at end of file diff --git a/src/pages/en/concepts/why-astro.md b/src/pages/en/concepts/why-astro.md new file mode 100644 index 0000000000000..898e51dab72e6 --- /dev/null +++ b/src/pages/en/concepts/why-astro.md @@ -0,0 +1,150 @@ +--- +layout: ~/layouts/MainLayout.astro +title: Why Astro? +description: DESCRIPTION +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 is designed for building content-rich websites. +2. [Server-first](#) -- Websites work better when they do more work 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 a JavaScript expert to build with Astro. +5. [Fully-featured, but flexible](#) -- Extend Astro with over 100+ integrations. + + + + + +## 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 other web frameworks are designed for building *data-rich web applications*. This includes websites that deal with lots of user interaction, state, and other data-driven experiences in the browser: Admin dashboards, web inboxes, lots of logged-in interactions, social networks, todo lists, and even full native-like software applications can run in your browser like Figma and Ping. + +This is one of the most important differences to understand about Astro. It's this focus that allows Astro to make tradeoffs and deliver innovative features that other frameworks simply cannot. Partial hydration, islands, and multi-framework support all wouldn't be possible without this focus. + + +:::tip +If you fall into the second "application" camp, Astro probably isn't 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 and minimizes client-side rendering as much as possible.** This is a time-tested approach that traditional server-side frameworks -- PHP, Wordpress, Laravel, Ruby on Rails, etc. etc. -- have been using for decades. But with Astro, you don't need to learn a second server-side language for your server code. It's all just HTML, CSS, and JavaScript/TypeScript. + +This approach stands in contrast to most modern JavaScript web frameworks, like Next.js, SvelteKit, Nuxt, Remix and others. These frameworks rely on client-side rendering of your entire website and will 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 they come at the expense of complexity and performance tradeoffs that don't make much sense for content-focused websites. Astro renders your components to static HTML on the server, where an SPA like Next.js would need to ship them to the user's browser as JavaScript to re-render a second time. This extra work harms page performance, including critical metrics like [Time to Interactive (TTI)](https://web.dev/interactive/). + + + + +📚 [Read more about Astro's MPA Architecture and why we chose it.](/en/concepts/mpa-vs-spa/) + + + + + + + + + + + +## Fast by default + +Good performance is always important, but it is *especially critical* for content-focused websites. Poor performance leaves engagement, conversion, and money on the table. 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)) + +**You shouldn't need to be an expert on web performance to build a fast website.** Astro's magic is in how it combines the two points above -- a content focus with a server-first MPA architecture -- to make tradeoffs and deliver features that other SPA frameworks cannot. The result is amazing web performance for every website, built into Astro itself. + +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 to a new developer, regardless of that person's skill level or past experience. + +To do this, we created our own `.astro` component syntax for rendering HTML on the server. You can always use your favorite component framework if you prefer (React, Svelte, Vue, and others are all supported) but we wanted to make sure that Astro had a great built-in component syntax as well. It's based on HTML, but has some of our favorite features borrowed from other component libraries like JSX-expressions for templating (React) and CSS scoping built-in (Svelte and Vue). + +Because Astro was designed for the server, it's language is incredibly simple when compared to other UI libraries that were originally designed for the client. 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 to worry about 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 featureset. + +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](https://www.npmjs.com/package/@astrojs/netlify) with just a single command. + +Where other SPA frameworks lock you into a single UI framework for your entire project, Astro has this idea of **Bring Your Own Framework (BYOF).** React, Preact, Solid, Svelte, Vue and Lit are all officially supported in Astro via a single, drop-in integration. You can even mix-and-match different frameworks on the same page, allowing for an easy migration in the future without framework lock-in. + + + + + + + + + + + + + + + + + + + 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/getting-started.md b/src/pages/en/getting-started.md index 1da1f43ceb9cc..33f1672289ef0 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 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-JavaScript, by default:** No JS 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. +- **Supports React, Preact, Svelte, Vue and all of your favorite UI frameworks!** -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: +Sounds interesting? Check out our detailed [Why Astro](/en/concepts/why-astro/) breakdown to learn more. + + +## 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 in no time with our easy `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,12 +62,12 @@ 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! +📚 [Add your first page](/en/core-concepts/astro-pages/) to your site. + 📚 Read more about Astro’s [project structure](/en/core-concepts/project-structure/). 📚 Learn about Astro's [template directives](/en/reference/directives-reference/). -📚 Explore Astro’s [runtime API](/en/reference/api-reference/). - *... find more material under **Reference*** From 2a65e7e8ef110ccd36061eb494185713de8ef4ef Mon Sep 17 00:00:00 2001 From: "Fred K. Schott" Date: Mon, 11 Jul 2022 15:44:49 -0700 Subject: [PATCH 2/7] ignore removed page from linkcheck --- netlify.toml | 10 +++++----- scripts/lint-slugcheck.mjs | 12 +++++++++++- src/i18n/de/nav.ts | 1 - src/i18n/es/nav.ts | 1 - src/i18n/fr/nav.ts | 1 - src/i18n/ja/nav.ts | 1 - src/i18n/pt-br/nav.ts | 1 - src/i18n/zh-cn/nav.ts | 1 - 8 files changed, 16 insertions(+), 12 deletions(-) diff --git a/netlify.toml b/netlify.toml index 4bd187b4232ee..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" @@ -30,7 +34,3 @@ to = "/:lang/404/" status = 404 - [[redirects]] - from = "/en/core-concepts/partial-hydration" - to = "/en/concepts/islands-architecture" - 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/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/es/nav.ts b/src/i18n/es/nav.ts index 5947a50d5a096..868095092f722 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 bced1c5c65552..00a3597a8d811 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': '组件', From 2c2edaf66a595d356329b7ec73151adc2ccc067e Mon Sep 17 00:00:00 2001 From: "Fred K. Schott" Date: Wed, 13 Jul 2022 15:26:14 -0700 Subject: [PATCH 3/7] respond to feedback --- src/pages/en/concepts/islands.md | 8 +++--- src/pages/en/concepts/mpa-vs-spa.md | 16 ++++++------ src/pages/en/concepts/why-astro.md | 38 +++++++++++++++-------------- src/pages/en/getting-started.md | 14 +++++------ 4 files changed, 39 insertions(+), 37 deletions(-) diff --git a/src/pages/en/concepts/islands.md b/src/pages/en/concepts/islands.md index 05c05a2c4a2c3..f019ab0a80af4 100644 --- a/src/pages/en/concepts/islands.md +++ b/src/pages/en/concepts/islands.md @@ -23,13 +23,13 @@ Component Island (or just "Island" for short) refers to an interactive UI compon Footer (static HTML) -You can use any 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. +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 at build-time and strip away all JavaScript. This keeps every site fast by default. +**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 --- @@ -58,9 +58,9 @@ The vast majority of your site remains pure, lightweight HTML and CSS. All you'v The most obvious benefit to islands architecture 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 non-blocking loading. In the example illustration above, the low-priority "image carosel" island doesn't 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 carosel lower down the page. +Another benefit is non-blocking loading. In the example illustration above, the low-priority "image carousel" island doesn't 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 carosel is really expensive to load, you can attach an special **client-directive** that tells Astro to only load the carosel when it becomes visible on the page. If the user never sees it, it never loads. +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 an special **client-directive** 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 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. diff --git a/src/pages/en/concepts/mpa-vs-spa.md b/src/pages/en/concepts/mpa-vs-spa.md index d511ee0ad1a9e..9cacc9e6672f5 100644 --- a/src/pages/en/concepts/mpa-vs-spa.md +++ b/src/pages/en/concepts/mpa-vs-spa.md @@ -11,13 +11,13 @@ Understanding the tradeoffs between Multi-Page Application (MPA) and Single-Page **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.** More traditional MPA frameworks also include Ruby on Rails, Python Django, PHP Laravel, Wordpress, and static site builders like Eleventy, Hugo and VitePress. -**A Single-Page Application (SPA)** is a website consisting of a JavaScript application that loads in the user's browser and then renders HTML locally. SPAs may *also* generate HTML on the server (especially for the the first page load) but SPAs are unique in their ability to render HTML locally when you navigate to a new page. Next.js, Nuxt, SvelteKit, Remix, Gatsby, and Create React App are all examples of SPA frameworks. +**A Single-Page Application (SPA)** is a website consisting of a JavaScript application that loads in the user's browser and then renders HTML locally. SPAs may *also* generate HTML on the server (especially for the first page load) but SPAs are unique in their ability to render HTML locally when you navigate to a new page. 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 unique from other MPA frameworks due to its use of JavaScript as a server runtime. Traditional MPA frameworks would have you write one language on the server (Ruby, PHP, etc.) and JavaScript on the browser. In Astro, you're always writing JavaScript. You can also re-use UI components (like React and Svelte) on both the server and the client. -The result is that Astro has a developer experience similar to that of Next.js or another modern SPA, even if the user experience is an entirely different MPA site architecture. +The result is a developer experience matching Next.js or any other modern SPA, with the user experience and improved performance of an MPA site architecture. ## MPAs vs. SPAs @@ -27,26 +27,26 @@ There are three main differences to be aware of when comparing MPAs vs. SPAs: In MPAs, most of your 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, a true SPAs (with no server rendering) will be consistently slower than an MPA. This is because an SPA has 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. +Rendering your HTML in the browser may sound like the faster option vs. requesting it from a remote server. However, an SPA without server rendering will be consistently slower than an MPA. 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. Server rendering the first page gives your user something to look at while your site loads in the background. However, this can introduce a new "uncanny valley" problem where your site appears loaded but unresponsive, since the application logic is still loading in the background. +Most SPA frameworks will attempt to mitigate this performance problem by adding basic server rendering on the first page load. Server rendering the first page gives your user something to look at while your site loads in the background. However, this can introduce a new "uncanny valley" problem where your site appears loaded but is unresponsive, since the application logic is still loading in the background. MPAs render all HTML on a remote server and often don't require much 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 may feel slower in MPAs vs. SPAs. #### 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 an SPA, your router runs right in the browser, and hijacks any navigation to render the new page locally without ever hitting a server. +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 runs right in the browser and hijacks any navigation to render the new page locally without ever hitting a server. -This is a similar tradeoff to the one described above: MPAs offer a faster first load experience, while SPAs sometimes ofer a faster second or third page load once the JavaScript application is fully loaded in the browser. +This is a similar tradeoff to the one described above: MPAs offer a faster first load experience, while SPAs sometimes offer a faster second or third page load once the JavaScript application is fully loaded in the browser. SPAs can also offer a more seamless navigation experience because they control rendering across the entire transition. To mitigate this, 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 model for complex state management. Because the entire website runs as a single JavaScript application in the browser, SPAs don't need to worry about maintaining state across page transitions. Both MPAs and most SPAs need to worry about server-side state for server rendering. +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". -SPAs really shine in complex websites that display lots of interactive data and need lots of JavaScript to run. Interactive, data-drive experiences like inboxes and admin dashboards do well as SPAs because the website itself is inherintely "app-like". + ## Are MPAs Better than SPAs? diff --git a/src/pages/en/concepts/why-astro.md b/src/pages/en/concepts/why-astro.md index 898e51dab72e6..c5ee593a03985 100644 --- a/src/pages/en/concepts/why-astro.md +++ b/src/pages/en/concepts/why-astro.md @@ -11,11 +11,11 @@ Why choose Astro over another web framework? Here are five core design principle #### Astro is... -1. [Content-focused](#) -- Astro is designed for building content-rich websites. -2. [Server-first](#) -- Websites work better when they do more work 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 a JavaScript expert to build with Astro. -5. [Fully-featured, but flexible](#) -- Extend Astro with over 100+ integrations. +1. [Content-focused](#): Astro is designed for building content-rich websites. +2. [Server-first](#): Websites work better when they do more work 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 a JavaScript expert to build with Astro. +5. [Fully-featured, but flexible](#): Extend Astro with over 100+ integrations. @@ -25,7 +25,7 @@ Why choose Astro over another web framework? Here are five core design principle **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 other web frameworks are designed for building *data-rich web applications*. This includes websites that deal with lots of user interaction, state, and other data-driven experiences in the browser: Admin dashboards, web inboxes, lots of logged-in interactions, social networks, todo lists, and even full native-like software applications can run in your browser like Figma and Ping. +By contrast, most modern web frameworks are designed for building *data-rich web applications*. This includes websites that deal with lots of user interaction, state, and other data-driven experiences in the browser: admin dashboards, web inboxes, lots of logged-in interactions, social networks, todo lists, and even full native-like software applications can run in your browser like Figma and Ping. This is one of the most important differences to understand about Astro. It's this focus that allows Astro to make tradeoffs and deliver innovative features that other frameworks simply cannot. Partial hydration, islands, and multi-framework support all wouldn't be possible without this focus. @@ -57,11 +57,11 @@ There's nothing wrong with those other frameworks! If you are building a rich we ## Server-first -**Astro leverages server-side rendering and minimizes client-side rendering as much as possible.** This is a time-tested approach that traditional server-side frameworks -- PHP, Wordpress, Laravel, Ruby on Rails, etc. etc. -- have been using for decades. But with Astro, you don't need to learn a second server-side language for your server code. It's all just HTML, CSS, and JavaScript/TypeScript. +**Astro leverages server-side rendering and minimizes client-side rendering as much as possible.** This is a time-tested approach that traditional server-side frameworks -- PHP, WordPress, Laravel, Ruby on Rails, etc. -- have been using for decades. But with Astro, you don't need to learn a second server-side language for your server code. It's all just HTML, CSS, and JavaScript/TypeScript. -This approach stands in contrast to most modern JavaScript web frameworks, like Next.js, SvelteKit, Nuxt, Remix and others. These frameworks rely on client-side rendering of your entire website and will 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. +This approach stands in contrast to most modern JavaScript web frameworks like Next.js, SvelteKit, Nuxt, Remix, and others. These frameworks rely on client-side rendering of your entire website and will 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 they come at the expense of complexity and performance tradeoffs that don't make much sense for content-focused websites. Astro renders your components to static HTML on the server, where an SPA like Next.js would need to ship them to the user's browser as JavaScript to re-render a second time. This extra work harms page performance, including critical metrics like [Time to Interactive (TTI)](https://web.dev/interactive/). +The SPA model has its benefits. However, these come at the expense of complexity and performance tradeoffs that don't make much sense for content-focused websites. Astro renders your components to static HTML on the server, where an SPA like Next.js would need to ship them to the user's browser as JavaScript to re-render a second time. This extra work harms page performance, including critical metrics like [Time to Interactive (TTI)](https://web.dev/interactive/). diff --git a/src/pages/en/getting-started.md b/src/pages/en/getting-started.md index 33f1672289ef0..637d73a3a4426 100644 --- a/src/pages/en/getting-started.md +++ b/src/pages/en/getting-started.md @@ -16,17 +16,17 @@ Astro is an **all-in-one** **web framework** for building **fast,** **content-fo - **Component Islands:** A new web architecture for building faster websites. - **Server-first API design:** Move expensive hydration off of your users' devices. -- **Zero-JavaScript, by default:** No JS runtime overhead to slow you down. +- **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. -- **Supports React, Preact, Svelte, Vue and all of your favorite UI frameworks!** +- **UI-agnostic:** Supports React, Preact, Svelte, Vue, Solid, Lit and more. -Sounds interesting? Check out our detailed [Why Astro](/en/concepts/why-astro/) breakdown to learn more. +Check out our detailed [Why Astro](/en/concepts/why-astro/) breakdown to learn more about what makes Astro special. ✨ ## Try Astro in your browser @@ -40,7 +40,7 @@ Visit [astro.new](https://astro.new/) and choose from a variety of templates to ## Start your first project -Get a new Astro 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 @@ -66,9 +66,9 @@ 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/). -📚 Learn about Astro's [template directives](/en/reference/directives-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 @@ -79,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/)*. From 85160b85fb499e56cdc730b263bb1f6941a7634b Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 14 Jul 2022 13:40:04 -0300 Subject: [PATCH 4/7] Update link in shared state page: partial-hydration -> islands (#985) --- src/pages/en/core-concepts/sharing-state.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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. From 9249b67ffa080f8762b6bb1e0dcb93938bf6851b Mon Sep 17 00:00:00 2001 From: "Fred K. Schott" Date: Tue, 26 Jul 2022 01:39:17 -0400 Subject: [PATCH 5/7] final pass --- src/i18n/en/nav.ts | 2 +- src/pages/en/concepts/islands.md | 26 ++++----- src/pages/en/concepts/mpa-vs-spa.md | 43 ++++---------- src/pages/en/concepts/why-astro.md | 88 +++++++---------------------- 4 files changed, 45 insertions(+), 114 deletions(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 8f6e98563acca..45864b04e8880 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -17,7 +17,7 @@ export default [ { text: 'Core Concepts', header: true, type: 'learn', key: 'coreConcepts' }, { 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: 'Component Islands', slug: 'concepts/islands', key: 'concepts/islands' }, + { 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' }, diff --git a/src/pages/en/concepts/islands.md b/src/pages/en/concepts/islands.md index f019ab0a80af4..7e7e498c903fe 100644 --- a/src/pages/en/concepts/islands.md +++ b/src/pages/en/concepts/islands.md @@ -1,17 +1,17 @@ --- layout: ~/layouts/MainLayout.astro -title: Component Islands +title: Astro Islands description: TODO i18nReady: true setup: | import IslandsDiagram from '~/components/IslandsDiagram.astro'; --- -**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. +**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 a Component Island? +## What is an Astro Island? -Component Island (or just "Island" for short) 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. +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) @@ -29,18 +29,18 @@ The technique that this architectural pattern builds on is known as **partial** ## 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 at build-time and strip away all JavaScript. This keeps every site fast by default. +**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 UIs. Astro doesn't force you to go 100% JavaScript to render the entire page. Instead, Astro will have you create an island. +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 --- @@ -52,16 +52,16 @@ import MyReactComponent from '../components/MyReactComponent.jsx'; ``` -The vast majority of your site remains pure, lightweight HTML and CSS. All you've added is a single, isolated **island of interactivity.** +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 islands architecture 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. +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 non-blocking loading. In the example illustration above, the low-priority "image carousel" island doesn't 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. +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 an special **client-directive** that tells Astro to only load the carousel when it becomes visible on the page. If the user never sees it, it never loads. +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 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. +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.** +**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 index 9cacc9e6672f5..95f097e7de012 100644 --- a/src/pages/en/concepts/mpa-vs-spa.md +++ b/src/pages/en/concepts/mpa-vs-spa.md @@ -9,15 +9,15 @@ Understanding the tradeoffs between Multi-Page Application (MPA) and Single-Page ## 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.** More traditional MPA frameworks also include Ruby on Rails, Python Django, PHP Laravel, Wordpress, and static site builders like Eleventy, Hugo and VitePress. +**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 JavaScript application that loads in the user's browser and then renders HTML locally. SPAs may *also* generate HTML on the server (especially for the first page load) but SPAs are unique in their ability to render HTML locally when you navigate to a new page. Next.js, Nuxt, SvelteKit, Remix, Gatsby, and Create React App are all examples of SPA frameworks. +**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 unique from other MPA frameworks due to its use of JavaScript as a server runtime. Traditional MPA frameworks would have you write one language on the server (Ruby, PHP, etc.) and JavaScript on the browser. In Astro, you're always writing JavaScript. You can also re-use UI components (like React and Svelte) on both the server and the client. +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 matching Next.js or any other modern SPA, with the user experience and improved performance of an MPA site architecture. +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 @@ -25,34 +25,33 @@ 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 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. +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, an SPA without server rendering will be consistently slower than an MPA. 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. +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. Server rendering the first page gives your user something to look at while your site loads in the background. However, this can introduce a new "uncanny valley" problem where your site appears loaded but is unresponsive, since the application logic is still loading in the background. +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 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 may feel slower in MPAs vs. SPAs. +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 runs right in the browser and hijacks any navigation to render the new page locally without ever hitting a server. +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 sometimes offer a faster second or third page load once the JavaScript application is fully loaded in the browser. +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 a more seamless navigation experience because they control rendering across the entire transition. To mitigate this, 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. +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 from the app-like behavior that SPAs bring at the expense of performance. +**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 @@ -70,21 +69,3 @@ If you know a public migration or benchmark and don't see it listed here, please 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) - - - - - - \ No newline at end of file diff --git a/src/pages/en/concepts/why-astro.md b/src/pages/en/concepts/why-astro.md index c5ee593a03985..d13d56ca89bde 100644 --- a/src/pages/en/concepts/why-astro.md +++ b/src/pages/en/concepts/why-astro.md @@ -11,93 +11,41 @@ Why choose Astro over another web framework? Here are five core design principle #### Astro is... -1. [Content-focused](#): Astro is designed for building content-rich websites. -2. [Server-first](#): Websites work better when they do more work on the server. +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 a JavaScript expert to build with Astro. -5. [Fully-featured, but flexible](#): Extend Astro with over 100+ integrations. - - - - +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 *data-rich web applications*. This includes websites that deal with lots of user interaction, state, and other data-driven experiences in the browser: admin dashboards, web inboxes, lots of logged-in interactions, social networks, todo lists, and even full native-like software applications can run in your browser like Figma and Ping. - -This is one of the most important differences to understand about Astro. It's this focus that allows Astro to make tradeoffs and deliver innovative features that other frameworks simply cannot. Partial hydration, islands, and multi-framework support all wouldn't be possible without this focus. +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 you fall into the second "application" camp, Astro probably isn't 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. +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 and minimizes client-side rendering as much as possible.** This is a time-tested approach that traditional server-side frameworks -- PHP, WordPress, Laravel, Ruby on Rails, etc. -- have been using for decades. But with Astro, you don't need to learn a second server-side language for your server code. It's all just HTML, CSS, and JavaScript/TypeScript. - -This approach stands in contrast to most modern JavaScript web frameworks like Next.js, SvelteKit, Nuxt, Remix, and others. These frameworks rely on client-side rendering of your entire website and will 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 complexity and performance tradeoffs that don't make much sense for content-focused websites. Astro renders your components to static HTML on the server, where an SPA like Next.js would need to ship them to the user's browser as JavaScript to re-render a second time. This extra work harms page performance, including critical metrics like [Time to Interactive (TTI)](https://web.dev/interactive/). - - - - -📚 [Read more about Astro's MPA Architecture and why we chose it.](/en/concepts/mpa-vs-spa/) - - - - - - - - - +📚 [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. Poor performance leaves engagement, conversion, and money on the table. For example: +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/)) @@ -106,20 +54,22 @@ Good performance is always important, but it is *especially critical* for conten - 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)) -**You shouldn't need to be an expert on web performance to build a fast website.** Astro's magic is in how it combines the two points above -- a content focus with a server-first MPA architecture -- to make tradeoffs and deliver features that other SPA frameworks cannot. The result is amazing web performance for every website, out of the box. +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 to a new developer, regardless of skill level or past experience. +**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 your favorite UI component framework with Astro. React, Preact, Svelte, Vue, Solid, Lit, and several others are all supported. +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. -But we wanted to make sure that Astro had a great built-in component syntax as well. So, we created our own `.astro` UI component language. It's heavily influenced by HTML, to the point that any valid snippet of HTML is already a valid Astro component. But it also has some of our favorite features borrowed from other component libraries, like JSX-like expressions (React) and CSS scoping by default (Svelte and Vue). +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 simpler and easier to learn than most other UI libraries. One big reason for this is that Astro was designed to run on the server and not in the browser. 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 to worry about on the server, so all of that complexity melts away. +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. From 51a8f9fbd1add2af59d257d2c38782cf55553572 Mon Sep 17 00:00:00 2001 From: "Fred K. Schott" Date: Tue, 26 Jul 2022 01:42:58 -0400 Subject: [PATCH 6/7] add descriptions --- src/pages/en/concepts/islands.md | 2 +- src/pages/en/concepts/mpa-vs-spa.md | 2 +- src/pages/en/concepts/why-astro.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/en/concepts/islands.md b/src/pages/en/concepts/islands.md index 7e7e498c903fe..1ae026c7694ac 100644 --- a/src/pages/en/concepts/islands.md +++ b/src/pages/en/concepts/islands.md @@ -1,7 +1,7 @@ --- layout: ~/layouts/MainLayout.astro title: Astro Islands -description: TODO +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'; diff --git a/src/pages/en/concepts/mpa-vs-spa.md b/src/pages/en/concepts/mpa-vs-spa.md index 95f097e7de012..48dc57e683b01 100644 --- a/src/pages/en/concepts/mpa-vs-spa.md +++ b/src/pages/en/concepts/mpa-vs-spa.md @@ -1,7 +1,7 @@ --- layout: ~/layouts/MainLayout.astro title: MPAs vs. SPAs -description: TODO +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 --- diff --git a/src/pages/en/concepts/why-astro.md b/src/pages/en/concepts/why-astro.md index d13d56ca89bde..f073985ce9e13 100644 --- a/src/pages/en/concepts/why-astro.md +++ b/src/pages/en/concepts/why-astro.md @@ -1,7 +1,7 @@ --- layout: ~/layouts/MainLayout.astro title: Why Astro? -description: DESCRIPTION +description: "Astro is an all-in-one web framework for building fast, content-focused websites. Learn more." i18nReady: true --- From bf906f2972556b0c928d670c02f642a5832afad0 Mon Sep 17 00:00:00 2001 From: "Fred K. Schott" Date: Tue, 26 Jul 2022 01:59:06 -0400 Subject: [PATCH 7/7] fix tests --- .../en/comparing-astro-vs-other-tools.md | 22 +++++++++---------- src/pages/en/concepts/why-astro.md | 2 +- .../en/core-concepts/partial-hydration.astro | 1 + src/pages/en/migration/0.21.0.astro | 2 +- 4 files changed, 14 insertions(+), 13 deletions(-) create mode 100644 src/pages/en/core-concepts/partial-hydration.astro 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/why-astro.md b/src/pages/en/concepts/why-astro.md index f073985ce9e13..a4b86b94618fd 100644 --- a/src/pages/en/concepts/why-astro.md +++ b/src/pages/en/concepts/why-astro.md @@ -78,7 +78,7 @@ One of our favorite sayings is: **opt-in to complexity.** We designed Astro to r **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. +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/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 @@ - +