|
| 1 | +# API 레퍼런스 |
| 2 | + |
| 3 | +## `createRenderer([options])` |
| 4 | + |
| 5 | +[options](#renderer-options)와 함께 [`Renderer`](#class-renderer)인스턴스를 만듭니다. |
| 6 | + |
| 7 | +```js |
| 8 | +const { createRenderer } = require('vue-server-renderer') |
| 9 | +const renderer = createRenderer({ ... }) |
| 10 | +``` |
| 11 | + |
| 12 | +## `createBundleRenderer(bundle[, options])` |
| 13 | + |
| 14 | +서버 번들과 [options](#renderer-options)을 이용해 [`BundleRenderer`](#class-bundlerenderer)인스턴스를 만듭니다. |
| 15 | + |
| 16 | +```js |
| 17 | +const { createBundleRenderer } = require('vue-server-renderer') |
| 18 | +const renderer = createBundleRenderer(serverBundle, { ... }) |
| 19 | +``` |
| 20 | + |
| 21 | +`serverBundle` 전달인자는 다음 중 하나입니다. |
| 22 | + |
| 23 | +- 절대경로를 가지는 번들파일(`.js` or `.json`). `/`로 시작해야 파일 경로로 판단합니다. |
| 24 | +- `vue-server-renderer/server-plugin`로 생성한 번들 객체입니다. |
| 25 | +- JavaScript 코드 문자열 (권장하지 않습니다.) |
| 26 | + |
| 27 | +[Introducing the Server Bundle](./bundle-renderer.md)와 [를 참조하세요.](./build-config.md) |
| 28 | + |
| 29 | +## `Class: Renderer` |
| 30 | + |
| 31 | +- #### `renderer.renderToString(vm[, context], callback)` |
| 32 | + |
| 33 | +Vue 인스턴스를 문자열로 렌더링합니다. 컨텍스트 객체는 옵션입니다. 콜백은 일반적인 Node.js 스타일이며 첫번째 전달인자는 오류, 두번째 전달인자는 렌더링된 문자열 입니다. |
| 34 | + |
| 35 | +- #### `renderer.renderToStream(vm[, context])` |
| 36 | + |
| 37 | +Vue 인스턴스를 Node.js 스트림으로 렌더링합니다. 컨텍스트 객체는 옵션입니다. 자세한 내용은 [스트리밍](./streaming.md)을 참조하세요. |
| 38 | + |
| 39 | +## `Class: BundleRenderer` |
| 40 | + |
| 41 | +- #### `bundleRenderer.renderToString([context, ]callback)` |
| 42 | + |
| 43 | +번들을 문자열로 렌더링합니다. 컨텍스트 객체는 옵션입니다. 콜백은 일반적인 Node.js 스타일이며 첫번째 전달인자는 오류, 두번째 전달인자는 렌더링된 문자열 입니다. |
| 44 | + |
| 45 | +- #### `bundleRenderer.renderToStream([context])` |
| 46 | + |
| 47 | +Vue 인스턴스를 Node.js 스트림으로 렌더링합니다. 컨텍스트 객체는 옵션입니다. 자세한 내용은 [스트리밍](./streaming.md)을 참조하세요. |
| 48 | + |
| 49 | +## 렌더러 옵션 |
| 50 | + |
| 51 | +- #### `template` |
| 52 | + |
| 53 | +전체 페이지 HTML에 대한 템플릿입니다. 템플릿에는 렌더링된 앱 컨텐츠의 플레이스홀더(placeholder) 역할을 하는 주석 `<!--vue-ssr-outlet-->`이 있어야 합니다. |
| 54 | + |
| 55 | +템플릿은 렌더링 컨텍스트를 사용하여 기본 인터폴레이션을 지원합니다. |
| 56 | + |
| 57 | +- 이중 mustache를 이용해 HTML 이스케이프 인터폴레이션(HTML-escaped-interpolation)을 합니다. |
| 58 | +- 삼중 mustache를 이용해 비 HTML 이스케이프 인터폴레이션(Non HTML-escaped-interpolation)을 합니다. |
| 59 | + |
| 60 | +템플릿은 렌더링 컨텍스트에서 특정 데이터가 발견되면 적절한 컨텐츠를 자동으로 주입합니다. |
| 61 | + |
| 62 | +- `context.head`: (string) 페이지 head에 삽입되어야하는 마크업 |
| 63 | +- `context.styles`: (string) 페이지 head에 삽입되어야하는 모든 인라인 CSS. 컴포넌트 CSS에 `vue-loader` + `vue-style-loader`를 사용하는 경우 이 속성이 자동으로 채워집니다. |
| 64 | +- `context.state`: (Object) `window.__INITIAL_STATE__`에서 반드시 인라인되어야하는 초기 Vuex store(저장소) state(상태) 인라인된 JSON은 XSS를 방지하기 위해 [serialize-javascript](https://github.com/yahoo/serialize-javascript)를 사용해 자동으로 삭제합니다. |
| 65 | + |
| 66 | +`clientManifest`이 제공되면 템플릿은 자동으로 아래 내용을 주입합니다. |
| 67 | + |
| 68 | +- 렌더링에 필요한 클라이언트 측 JavaScript 및 CSS 에셋 (비동기 청크가 자동으로 유추됨) |
| 69 | +- 최적의 `<link rel="preload/prefetch"> 렌더링된 페`이지에 대한 리소스 힌트 |
| 70 | + |
| 71 | +렌더러에 `inject: false`를 전달하여 모든 자동 주입을 비활성화 할 수 있습니다. |
| 72 | + |
| 73 | +참고하세요 |
| 74 | + |
| 75 | +- [페이지 템플릿 사용](./basic.md#using-a-page-template) |
| 76 | +- [수동 에셋 주입](./build-config.md#manual-asset-injection) |
| 77 | + - #### `clientManifest` |
| 78 | +- 2.3.0+ |
| 79 | + |
| 80 | +`vue-server-renderer/client-plugin`에 의해 생성된 클라이언트 매니페스트 객체를 제공합니다. 클라이언트 매니페스트는 번들 렌더러에게 HTML 템플릿으로 자동 에셋 주입을 위한 적절한 정보를 제공합니다. 자세한 내용은[Generating clientManifest](./build-config.md#generating-clientmanifest)을 참조하세요. |
| 81 | + |
| 82 | +- |
| 83 | +#### `inject` |
| 84 | + |
| 85 | + - 2.3.0+ |
| 86 | + |
| 87 | +`template`을 사용할 때 자동 주입 여부를 선택합니다. 기본값은 `true`입니다. |
| 88 | + |
| 89 | +[Manual Asset Injection](./build-config.md#manual-asset-injection)을 참조하세요 |
| 90 | + |
| 91 | +- |
| 92 | +#### `shouldPreload` |
| 93 | + |
| 94 | + - 2.3.0+ |
| 95 | + |
| 96 | +`<link rel="preload"> 리소스 힌트`가 생성되어야하는 파일을 제어하는 함수입니다. |
| 97 | + |
| 98 | +기본적으로 애플리케이션 시작에 절대적으로 필요한 JavaScript 및 CSS파일만 미리 로드합니다. |
| 99 | + |
| 100 | +이미지 또는 글꼴과 같은 다른 유형의 에셋의 경우 프리로드를 너무 많이하면 대역폭을 낭비하고 성능을 저하시키므로 프리로드할 대상은 시나리오에 따라 달라야합니다. `shouldPreload`옵션을 사용하여 프리로드할 항목을 정확하게 선택해야합니다. |
| 101 | + |
| 102 | +```js |
| 103 | + const renderer = createBundleRenderer(bundle, { |
| 104 | + template, |
| 105 | + clientManifest, |
| 106 | + shouldPreload: (file, type) => { |
| 107 | + // type is inferred based on the file extension. |
| 108 | + // https://fetch.spec.whatwg.org/#concept-request-destination |
| 109 | + if (type === 'script' || type === 'style') { |
| 110 | + return true |
| 111 | + } |
| 112 | + if (type === 'font') { |
| 113 | + // only preload woff2 fonts |
| 114 | + return /\.woff2$/.test(file) |
| 115 | + } |
| 116 | + if (type === 'image') { |
| 117 | + // only preload important images |
| 118 | + return file === 'hero.jpg' |
| 119 | + } |
| 120 | + } |
| 121 | + }) |
| 122 | +``` |
| 123 | + |
| 124 | +- |
| 125 | +#### `runInNewContext` |
| 126 | + |
| 127 | + - 2.3.0+ |
| 128 | + - `createBundleRenderer`에서만 사용할 수 있습니다. |
| 129 | + - 예상: `boolean | 'once'` (`'once'` 2.3.1+ 에서만 지원함) |
| 130 | + |
| 131 | +기본적으로 각 렌더에 대해 번들 렌더러는 새로운 V8 컨텍스트를 만들고 전체 번들을 다시 실행합니다. 이는 몇가지 장점을 가집니다. 예를 들어 애플리케이션 코드는 서버 프로세스와 분리되어 있으며 문서에 언급된 [stateful singleton problem](./structure.md#avoid-stateful-singletons)에 대해 걱정할 필요가 없습니다. 그러나 번들을 다시 실행하는 것은 앱이 커지면 비용이 많이 들기 때문에 이 모드는 상당한 성능 비용을 발생시킵니다. |
| 132 | + |
| 133 | +이 옵션은 하위 호환성을 위해 `true`가 기본값이지만 가능할 때마다 `runInNewContext: false` 또는 `runInNewContext: 'once'`를 사용하는 것이 좋습니다. |
| 134 | + |
| 135 | +> 2.3.0에서 이 옵션은 `runInNewContext: false`가 별도의 전역 컨텍스트를 사용하여 번들을 실행하는 버그가 있습니다. 2.3.1버전 이후 버전을 사용한다고 가정합니다. |
| 136 | +
|
| 137 | +`runInNewContext: false`를 사용하면 번들 코드가 서버 프로세스와 동일한 `global` 컨텍스트에서 실행되므로 애플리케이션 코드에서 `global`을 수정하는 코드를 주의해야 합니다. |
| 138 | + |
| 139 | +`runInNewContext: 'once'`(2.3.1+)를 사용하면 번들은 별도의 `global` 컨텍스트로 평가되지만 시작할 때 한번 뿐입니다. 번들이 실수로 서버 프로세스의 `global` 객체를 오염시키는 것을 방지하므로 더 안전한 코드 관리를 할 수 있습니다. 주의사항은 다음과 같습니다. |
| 140 | + |
| 141 | +1. 이 모드에서는 `global`(예: 폴리필)을 수정하는 의존성을 외부에 둘 수 없습니다. |
| 142 | +2. 번들 실행에서 반환된 값은 다른 전역 생성자를 사용합니다. 번들 내부에서 발견된 오류는 서버 프로세스에서 `Error` 인스턴스가 되지 않습니다. |
| 143 | + |
| 144 | +[Source Code Structure](./structure.md)를 참조하세요 |
| 145 | + |
| 146 | +- |
| 147 | +#### `basedir` |
| 148 | + |
| 149 | + - 2.2.0+ |
| 150 | + - `createBundleRenderer`에서만 사용할 수 있습니다. |
| 151 | + |
| 152 | +`node_modules` 종속성 처리를 위해 서버 번들의 기본 디렉토리를 명시적으로 선언해야합니다. 생성된 번들 파일이 외부화된 NPM 종속성이 설치되어있거나 `vue-server-renderer`가 npm으로 연결된 다른 위치에 있는 경우에만 필요합니다. |
| 153 | + |
| 154 | +- #### `cache` |
| 155 | + |
| 156 | +[컴포넌트 캐시](./caching.md#component-level-caching)를 제공합니다. 캐시 객체는 Flow 표기법을 사용하여 다음 인터페이스를 구현해야합니다. |
| 157 | + |
| 158 | +```js |
| 159 | + type RenderCache = { |
| 160 | + get: (key: string, cb?: Function) => string | void; |
| 161 | + set: (key: string, val: string) => void; |
| 162 | + has?: (key: string, cb?: Function) => boolean | void; |
| 163 | + }; |
| 164 | +``` |
| 165 | + |
| 166 | +[lru-cache](https://github.com/isaacs/node-lru-cache):일반적으로 [lru-cache](https://github.com/isaacs/node-lru-cache)를 전달하여 사용합니다. |
| 167 | + |
| 168 | +```js |
| 169 | + const LRU = require('lru-cache') |
| 170 | + const renderer = createRenderer({ |
| 171 | + cache: LRU({ |
| 172 | + max: 10000 |
| 173 | + }) |
| 174 | + }) |
| 175 | +``` |
| 176 | + |
| 177 | +캐시 객체는 최소한 `get`과 `set`을 구현해야합니다. 또한 두번째 전달인자를 콜백으로 허용하면 `get`과 `has`는 선택적으로 비동기화할 수 있습니다. 이렇게하면 캐시에서 비동기 API를 사용할 수 있습니다. 예: redis 클라이언트 |
| 178 | + |
| 179 | +```js |
| 180 | + const renderer = createRenderer({ |
| 181 | + cache: { |
| 182 | + get: (key, cb) => { |
| 183 | + redisClient.get(key, (err, res) => { |
| 184 | + // handle error if any |
| 185 | + cb(res) |
| 186 | + }) |
| 187 | + }, |
| 188 | + set: (key, val) => { |
| 189 | + redisClient.set(key, val) |
| 190 | + } |
| 191 | + } |
| 192 | + }) |
| 193 | +``` |
| 194 | + |
| 195 | +- #### `directives` |
| 196 | + |
| 197 | +사용자 정의 디렉티브에 대한 서버측 구현을 제공할 수 있습니다. |
| 198 | + |
| 199 | +```js |
| 200 | + const renderer = createRenderer({ |
| 201 | + directives: { |
| 202 | + example (vnode, directiveMeta) { |
| 203 | + // transform vnode based on directive binding metadata |
| 204 | + } |
| 205 | + } |
| 206 | + }) |
| 207 | +``` |
| 208 | + |
| 209 | +[`v-show`의 서버측 구현](https://github.com/vuejs/vue/blob/dev/src/platforms/web/server/directives/show.js)을 확인하세요 |
| 210 | + |
| 211 | +## webpack 플러그인 |
| 212 | + |
| 213 | +webpack 플러그인은 독립실행형으로 제공되므로 직접 require 해야합니다. |
| 214 | + |
| 215 | +```js |
| 216 | +const VueSSRServerPlugin = require('vue-server-renderer/server-plugin') |
| 217 | +const VueSSRClientPlugin = require('vue-server-renderer/client-plugin') |
| 218 | +``` |
| 219 | + |
| 220 | +생성되는 기본 파일입니다. |
| 221 | + |
| 222 | +- 서버 플러그인을 위한 `vue-ssr-server-bundle.json` |
| 223 | +- 클라이언트 플러그인을 위한 `vue-ssr-client-manifest.json` |
| 224 | + |
| 225 | +파일 이름은 플러그인 인스턴스를 생성할 때 사용자 정의할 수 있습니다. |
| 226 | + |
| 227 | +```js |
| 228 | +const plugin = new VueSSRServerPlugin({ |
| 229 | + filename: 'my-server-bundle.json' |
| 230 | +}) |
| 231 | +``` |
| 232 | + |
| 233 | +[빌드 설정](./build-config.md)을 참조하세요. |
0 commit comments