From ddfc6ca307c4f6685ad5ccfe6adf8416216f9050 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Fri, 26 May 2023 08:20:18 -0400 Subject: [PATCH 1/6] Unflag hybrid rendering docs --- src/content/docs/en/guides/server-side-rendering.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 5fd68ccdd172a..67bab54f638b5 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -151,9 +151,6 @@ export { defineConfig } from 'astro/config'; export default defineConfig({ output: 'hybrid', - experimental: { - hybridOutput: true, - }, }); ``` From c19038bdba515196d20f764a260dd5c078298fa0 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Fri, 26 May 2023 12:42:13 -0400 Subject: [PATCH 2/6] Update the hybrid rendering section to explain both modes --- .../docs/en/guides/server-side-rendering.mdx | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 67bab54f638b5..50d7c70caf14f 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -103,9 +103,12 @@ Astro will remain a static-site generator by default. But once you enable a serv -Any individual [page](/en/core-concepts/astro-pages/) or [server endpoint](/en/core-concepts/endpoints/#server-endpoints-api-routes) that supports exporting variables (`.astro`, `.mdx`, `.ts`, or `.js`) can opt in to pre-rendering when your Astro project is configured to use SSR with `output: server`. These files will be statically rendered at build-time, similar to the default [`output: static`](/en/reference/configuration-reference/#output) mode. +Hybrid rendering is when you have a site where some pages are prerendered to HTML and some are server rendered. There are two ways to do prerendering: -Simply add `export const prerender = true`: +- __`output: 'server'`__: Any individual [page](/en/core-concepts/astro-pages/) or [server endpoint](/en/core-concepts/endpoints/#server-endpoints-api-routes) can be prerendered. +- __`output: 'hybrid'`__: Any page or endpoint can be marked to *not* be prerendered. Use this when most of your site should be static. + +For a mostly-server rerendered app, simply add `export const prerender = true`: ```astro title="src/pages/mypage.astro" {2} --- @@ -127,6 +130,7 @@ export const prerender = true; # This is my page ``` +And for an endpoint: ```js title="src/pages/myendpoint.js" {1} export const prerender = true; @@ -138,23 +142,20 @@ export async function get() { } ``` -#### Static pre-rendering by default - - - -You may have a site that is *mostly* static and can benefit from pre-rendering, but only a few of your pages or endpoints need to be server-rendered. SSR in Astro defaults to rendering on the server and requires you to individually designate the pages that should be static. +In a static site you can mark some routes to be server-rendered. To do this, change the `output` to `'hybrid'` and add an adapter: -To avoid declaring most of your pages as pre-rendered, change the `output` from `'server'` to `'hybrid'` and take advantage of SSR with static pre-rendering by default: - -```js -export { defineConfig } from 'astro/config'; +```diff +import { defineConfig } from 'astro/config'; ++ import nodejs from '@astrojs/nodejs'; export default defineConfig({ - output: 'hybrid', ++ adapter: nodejs(), ++ output: 'hybrid', +- output: 'static', }); ``` -With this configuration, all of your pages and API endpoints will be pre-rendered, even though your project is configured with an adapter to use SSR. You can then *opt-out* of pre-rendering any individual file or route by adding `export const prerender = false` to any files that should be server-rendered. +You can then *opt-out* of pre-rendering any individual file or route by adding `export const prerender = false` to any files that should be server-rendered. ```js title="src/pages/randomnumber.js" {1} export const prerender = false; From 7a1b0d8eb9a341aae61acbc4701ec86a763050c3 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 31 May 2023 12:41:18 -0300 Subject: [PATCH 3/6] restructure SSR options on page (#3378) Co-authored-by: Nate Moore --- .../docs/en/guides/server-side-rendering.mdx | 67 ++++++++++++------- 1 file changed, 42 insertions(+), 25 deletions(-) diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 50d7c70caf14f..3951cf7e46f25 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -13,7 +13,10 @@ import Since from '~/components/Since.astro'; ## Enabling SSR in Your Project -To get started, enable SSR features in development mode with the `output: server` configuration option: +To enable SSR features for production deployments, update your `output` configuration to `'server'` or `'hybrid'` (introduced in **v2.6.0**). Both of these modes control which [pages](/en/core-concepts/astro-pages/) or [server endpoints](/en/core-concepts/endpoints/#server-endpoints-api-routes) should be server-rendered. Each configuration option has a different default behavior, and allows individual routes to opt-out of the default accordingly: + +- __`output: 'server'`__: Server-rendered by default. Use this when most or all of your site should be server-rendered. Any individual page or endpoint can *opt-in* to pre-rendering. +- __`output: 'hybrid'`__: Pre-rendered to HTML by default. Use this when most of your site should be static. Any individual page or endpoint can *opt-out* of pre-rendering. ```js ins={5} // astro.config.mjs @@ -24,6 +27,34 @@ export default defineConfig({ }); ``` +You can then opt-out of the default rendering behavior with an export statement in any page or route: + +```astro title="src/pages/mypage.astro" {2} +--- +export const prerender = true; +// ... +--- + + + +``` +See more usage examples of [configuring individual routes](#configuring-individual-routes) + +### Converting a static site to hybrid rendering + +To convert an existing static Astro site to allow hybrid rendering, change the `output` to `'hybrid'` and add an adapter: + +```diff +import { defineConfig } from 'astro/config'; ++ import nodejs from '@astrojs/nodejs'; + +export default defineConfig({ ++ adapter: nodejs(), ++ output: 'hybrid', +- output: 'static', +}); +``` + ### Adding an Adapter When it's time to deploy an SSR project, you also need to add an adapter. This is because SSR requires a server _runtime_: the environment that runs your server-side code. Each adapter allows Astro to output a script that runs your project on a specific runtime. @@ -97,18 +128,15 @@ You can also add an adapter manually by installing the package and updating `ast ## Features -Astro will remain a static-site generator by default. But once you enable a server-side rendering adapter, **every route in your pages directory defaults to a server-rendered route** and a few new features become available to you. +Astro will remain a static-site generator by default. But once you enable server-side rendering and add an adapter, a few new features become available to you. -### Hybrid Rendering +### Configuring individual routes - +Both `server` and `hybrid` modes allow for server-rendered pages and endpoints and will render all pages according to their default mode. However, both modes allow you to mark an individual page to opt-out of this default behavior. -Hybrid rendering is when you have a site where some pages are prerendered to HTML and some are server rendered. There are two ways to do prerendering: +### Opting-out of server-rendering -- __`output: 'server'`__: Any individual [page](/en/core-concepts/astro-pages/) or [server endpoint](/en/core-concepts/endpoints/#server-endpoints-api-routes) can be prerendered. -- __`output: 'hybrid'`__: Any page or endpoint can be marked to *not* be prerendered. Use this when most of your site should be static. - -For a mostly-server rerendered app, simply add `export const prerender = true`: +For a mostly server-rendered app configured as `output: server`, add `export const prerender = true` to any page or route to pre-render a static page or endpoint: ```astro title="src/pages/mypage.astro" {2} --- @@ -116,7 +144,7 @@ export const prerender = true; // ... --- - + ``` @@ -127,7 +155,7 @@ title: 'My page' --- export const prerender = true; -# This is my page +# This is my static, pre-rendered page ``` And for an endpoint: @@ -137,25 +165,14 @@ export const prerender = true; export async function get() { return { - body: JSON.stringify({ message: `This is my endpoint` }), + body: JSON.stringify({ message: `This is my static endpoint` }), }; } ``` -In a static site you can mark some routes to be server-rendered. To do this, change the `output` to `'hybrid'` and add an adapter: - -```diff -import { defineConfig } from 'astro/config'; -+ import nodejs from '@astrojs/nodejs'; - -export default defineConfig({ -+ adapter: nodejs(), -+ output: 'hybrid', -- output: 'static', -}); -``` +### Opting out of pre-rendering -You can then *opt-out* of pre-rendering any individual file or route by adding `export const prerender = false` to any files that should be server-rendered. +For a mostly static site configured as `output: hybrid`, add `export const prerender = false` to any files that should be server-rendered: ```js title="src/pages/randomnumber.js" {1} export const prerender = false; From 93ac2e0b88651423ee4ce98a47e8707d83dc4eb7 Mon Sep 17 00:00:00 2001 From: Nate Moore Date: Wed, 31 May 2023 11:01:00 -0500 Subject: [PATCH 4/6] chore: update outdated links --- src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx | 2 +- src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx | 2 +- src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx | 2 +- src/content/docs/en/guides/upgrade-to/v2.mdx | 2 +- src/content/docs/ja/guides/upgrade-to/v2.mdx | 2 +- src/content/docs/ko/guides/upgrade-to/v2.mdx | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx index 7e20a6b1e203b..0785a7d207695 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx @@ -23,7 +23,7 @@ Gatsby and Astro share some similarities that will help you migrate your project - Astro has support for [installing NPM packages](/en/guides/imports/#npm-packages), including React libraries. Many of your existing dependencies will work in Astro. -- Like Gatsby, Astro projects can be SSG or [SSR with page-level prerendering](/en/guides/server-side-rendering/#hybrid-rendering). +- Like Gatsby, Astro projects can be SSG or [SSR with page-level prerendering](/en/guides/server-side-rendering/#configuring-individual-routes). ## Key Differences between Gatsby and Astro diff --git a/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx b/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx index 067b0398cc673..beed148adb50b 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx @@ -16,7 +16,7 @@ Here are some key concepts and migration strategies to help you get started. Use Next.js and Astro share some similarities that will help you migrate your project: - The [syntax of `.astro` files is similar to JSX](/en/core-concepts/astro-syntax/#differences-between-astro-and-jsx). Writing Astro should feel familiar. -- Astro projects can also be SSG or [SSR with page-level prerendering](/en/guides/server-side-rendering/#hybrid-rendering). +- Astro projects can also be SSG or [SSR with page-level prerendering](/en/guides/server-side-rendering/#configuring-individual-routes). - Astro uses file-based routing, and [allows specially named pages to create dynamic routes](/en/core-concepts/routing/#dynamic-routes). - Astro is [component-based](/en/core-concepts/astro-components/), and your markup structure will be similar before and after your migration. - Astro has [official integrations for React, Preact, and Solid](/en/guides/integrations-guide/react/) so you can use your existing JSX components. Note that in Astro, these files **must** have a `.jsx` or `.tsx` extension. diff --git a/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx b/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx index 1aa2ff3e96fd8..b154cb85a8f42 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx @@ -18,7 +18,7 @@ Here are some key concepts and migration strategies to help you get started. Use Nuxt and Astro share some similarities that will help you migrate your project: -- Astro projects can also be SSG or [SSR with page level prerendering](/en/guides/server-side-rendering/#hybrid-rendering). +- Astro projects can also be SSG or [SSR with page level prerendering](/en/guides/server-side-rendering/#configuring-individual-routes). - Astro uses file-based routing, and [allows specially named pages to create dynamic routes](/en/core-concepts/routing/#dynamic-routes). - Astro is [component-based](/en/core-concepts/astro-components/), and your markup structure will be similar before and after your migration. - Astro has [an official integration for using Vue components](/en/guides/integrations-guide/vue/). diff --git a/src/content/docs/en/guides/upgrade-to/v2.mdx b/src/content/docs/en/guides/upgrade-to/v2.mdx index 6e9a33bf5344a..1adbcf73b3982 100644 --- a/src/content/docs/en/guides/upgrade-to/v2.mdx +++ b/src/content/docs/en/guides/upgrade-to/v2.mdx @@ -415,7 +415,7 @@ export default defineConfig({ These features are now available by default: - [Content collections](/en/guides/content-collections/) as a way to manage your Markdown and MDX files with type-safety. -- [Prerendering individual pages to static HTML](/en/guides/server-side-rendering/#hybrid-rendering) when using SSR to improve speed and cacheability. +- [Prerendering individual pages to static HTML](/en/guides/server-side-rendering/#configuring-individual-routes) when using SSR to improve speed and cacheability. - A redesigned error message overlay. ## Known Issues diff --git a/src/content/docs/ja/guides/upgrade-to/v2.mdx b/src/content/docs/ja/guides/upgrade-to/v2.mdx index 6be5705da95f0..03b6f37588042 100644 --- a/src/content/docs/ja/guides/upgrade-to/v2.mdx +++ b/src/content/docs/ja/guides/upgrade-to/v2.mdx @@ -415,7 +415,7 @@ export default defineConfig({ これらの機能は、デフォルトで利用できるようになりました。 - MarkdownやMDXのファイルを型安全で管理する方法として、[コンテンツコレクション](/ja/guides/content-collections/)があります。 -{/* TODO: Set anchor link from #機能 to #hybrid-rendering */} +{/* TODO: Set anchor link from #機能 to #configuring-individual-routes */} - SSR使用時に[個別ページ静的HTMLにプリレンダリング](/ja/guides/server-side-rendering/#機能)をし、高速化とキャッシュ性能の向上を図る。 - エラーメッセージのオーバーレイのデザインを変更しました。 diff --git a/src/content/docs/ko/guides/upgrade-to/v2.mdx b/src/content/docs/ko/guides/upgrade-to/v2.mdx index faf9eb1da53c9..487f20ac01c59 100644 --- a/src/content/docs/ko/guides/upgrade-to/v2.mdx +++ b/src/content/docs/ko/guides/upgrade-to/v2.mdx @@ -411,7 +411,7 @@ export default defineConfig({ 다음 기능들이 이제 기본적으로 사용이 가능해졌습니다: - [Content Collections](/ko/guides/content-collections/)을 사용하여 Markdown과 MDX 파일을 타입 안전하게 관리할 수 있습니다. -- [Prerendering individual pages to static HTML](/ko/guides/server-side-rendering/#hybrid-rendering)을 사용하여 속도와 캐시 가능성을 개선할 수 있습니다. +- [Prerendering individual pages to static HTML](/ko/guides/server-side-rendering/#configuring-individual-routes)을 사용하여 속도와 캐시 가능성을 개선할 수 있습니다. - 에러 메세지 오버레이의 디자인을 바꾸었습니다. ## 발견된 이슈 From 23c861ee0fafeb91af3ea79c0093359340029db8 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 31 May 2023 12:06:59 -0400 Subject: [PATCH 5/6] Update src/content/docs/en/guides/server-side-rendering.mdx Co-authored-by: Nate Moore --- src/content/docs/en/guides/server-side-rendering.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 3951cf7e46f25..a57a236ff7227 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -51,7 +51,6 @@ import { defineConfig } from 'astro/config'; export default defineConfig({ + adapter: nodejs(), + output: 'hybrid', -- output: 'static', }); ``` From 3f9515738fda4f2995ca988ad14d5d83b2d046d1 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 6 Jun 2023 14:01:30 -0300 Subject: [PATCH 6/6] Update v2.mdx --- src/content/docs/pl/guides/upgrade-to/v2.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/pl/guides/upgrade-to/v2.mdx b/src/content/docs/pl/guides/upgrade-to/v2.mdx index 39f385fde83df..e8d3252a72a30 100644 --- a/src/content/docs/pl/guides/upgrade-to/v2.mdx +++ b/src/content/docs/pl/guides/upgrade-to/v2.mdx @@ -409,7 +409,7 @@ export default defineConfig({ Te funkcje są teraz domyślnie dostępne: - [Kolekcje Treści](/pl/guides/content-collections/) jako sposób na zarządzanie plikami Markdown i MDX z zabezpieczeniem typów. -- [Prerenderowanie pojedynczych stron do statycznego HTML](/pl/guides/server-side-rendering/#hybrid-rendering) przy użyciu SSR w celu poprawy szybkości i możliwości cachowania. +- [Prerenderowanie pojedynczych stron do statycznego HTML](/pl/guides/server-side-rendering/#configuring-individual-routes) przy użyciu SSR w celu poprawy szybkości i możliwości cachowania. - Zmieniony wygląd nakładki z komunikatem o błędzie. ## Znane problemy