Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Unflag hybrid rendering docs #3353

Merged
merged 9 commits into from
Jun 6, 2023
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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/).
Expand Down
71 changes: 43 additions & 28 deletions src/content/docs/en/guides/server-side-rendering.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
// ...
---
<html>
<!-- Static, pre-rendered page here... -->
</html>
```
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',
matthewp marked this conversation as resolved.
Show resolved Hide resolved
});
```

### 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.
Expand Down Expand Up @@ -97,23 +128,23 @@ 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

<Since v="2.0.0" />
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.

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.
### Opting-out of server-rendering

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}
---
export const prerender = true;
// ...
---
<html>
<!-- Page here... -->
<!-- Static, pre-rendered page here... -->
</html>
```

Expand All @@ -124,40 +155,24 @@ title: 'My page'
---
export const prerender = true;

# This is my page
# This is my static, pre-rendered page
```

And for an endpoint:

```js title="src/pages/myendpoint.js" {1}
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` }),
};
}
```

#### Static pre-rendering by default

<Since v="2.5.0" />

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.

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';

export default defineConfig({
output: 'hybrid',
experimental: {
hybridOutput: true,
},
});
```
### Opting out of pre-rendering

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.
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;
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/en/guides/upgrade-to/v2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/ja/guides/upgrade-to/v2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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/#機能)をし、高速化とキャッシュ性能の向上を図る。
- エラーメッセージのオーバーレイのデザインを変更しました。

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/ko/guides/upgrade-to/v2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)을 사용하여 속도와 캐시 가능성을 개선할 수 있습니다.
- 에러 메세지 오버레이의 디자인을 바꾸었습니다.

## 발견된 이슈
Expand Down