diff --git a/ko/build-config.md b/ko/build-config.md new file mode 100644 index 00000000..276a4b97 --- /dev/null +++ b/ko/build-config.md @@ -0,0 +1,202 @@ +# 빌드 설정 + +클라이언트 전용 프로젝트를 위해 webpack을 구성하는 방법을 이미 알고있다고 가정합니다. SSR 프로젝트 설정은 거의 유사하지만 구성을 세가지로(*기본*, *클라이언트*와 *서버*)로 나누는 것이 좋습니다. 기본 구성에는 출력될 경로 별칭 및 로더와 같은 두 환경에 공유되는 설정들이 있습니다. 서버와 클라이언트 설정은 단순히 [webpack-merge](https://github.com/survivejs/webpack-merge)를 사용해 기본 설정을 확장합니다. + +## 서버 설정 + +서버 설정은 `createBundleRenderer`에 전달될 서버 번들을 생성하기 위한 것 입니다. 아래와 같습니다. + +```js +const merge = require('webpack-merge') +const nodeExternals = require('webpack-node-externals') +const baseConfig = require('./webpack.base.config.js') +const VueSSRServerPlugin = require('vue-server-renderer/server-plugin') +module.exports = merge(baseConfig, { + // Point entry to your app's server entry file + entry: '/path/to/entry-server.js', + // This allows webpack to handle dynamic imports in a Node-appropriate + // fashion, and also tells `vue-loader` to emit server-oriented code when + // compiling Vue components. + target: 'node', + // For bundle renderer source map support + devtool: 'source-map', + // This tells the server bundle to use Node-style exports + output: { + libraryTarget: 'commonjs2' + }, + // https://webpack.js.org/configuration/externals/#function + // https://github.com/liady/webpack-node-externals + // Externalize app dependencies. This makes the server build much faster + // and generates a smaller bundle file. + externals: nodeExternals({ + // do not externalize dependencies that need to be processed by webpack. + // you can add more file types here e.g. raw *.vue files + // you should also whitelist deps that modifies `global` (e.g. polyfills) + whitelist: /\.css$/ + }), + // This is the plugin that turns the entire output of the server build + // into a single JSON file. The default file name will be + // `vue-ssr-server-bundle.json` + plugins: [ + new VueSSRServerPlugin() + ] +}) +``` + +`vue-ssr-server-bundle.json`이 생성된 후 파일 경로를 `createBundleRenderer`에 전달합니다. + +```js +const { createBundleRenderer } = require('vue-server-renderer') +const renderer = createBundleRenderer('/path/to/vue-ssr-server-bundle.json', { + // ...other renderer options +}) +``` + +또는, 번들을 Object로 만들어 `createBundleRenderer`에 전달할 수 있습니다. 이는 개발중 핫 리로드를 사용할 때 유용합니다. HackerNews 데모의 [설정](https://github.com/vuejs/vue-hackernews-2.0/blob/master/build/setup-dev-server.js)을 참조하세요. + +### Externals 주의사항 + +`externals`옵션에서는 CSS파일을 허용하는 목록에 추가합니다. 의존성에서 가져온 CSS는 여전히 webpack에서 처리해야합니다. webpack을 사용하는 다른 유형의 파일을 가져오는 경우(예: `*.vue`, `*.sass`) 파일을 허용 목록에 추가해야합니다. + +`runInNewContext: 'once'` 또는 `runInNewContext: true`를 사용하는 경우 `전역 변수`를 수정하는 폴리필을 허용 목록에 추가해야합니다. 예를 들어 `babel-polyfill`이 있습니다. 새 컨텍스트 모드를 사용할 때 **서버 번들의 내부 코드가 자체적으로 `전역` 객체를 가지고 있기 때문입니다.** Node 7.6버전 이상을 사용할 때 서버에서는 실제로 필요하지 않으므로 클라이언트에서 가져오는 것이 더 쉽습니다. + +## 클라이언트 설정 + +클라이언트 설정은 기본 설정과 거의 동일합니다. 클라이언트의 `entry`파일을 가리키면 됩니다. 그 외에도 `CommonsChunkPlugin`을 사용하는 경우 서버 번들에 단일 entry 청크가 필요하기 때문에 클라이언트 설정에서만 사용해야합니다. + +### `clientManifest` 생성 + +> 2.3.0버전 이후 지원 + +서버 번들 외에도 클라이언트 빌드 매니페스트를 생성할 수도 있습니다. 클라이언트 매니페스트와 서버 번들을 사용하면 렌더러에 서버 및 클라이언트 빌드 정보가 *모두* 포함되므로 [프리로드/프리페치 디렉티브](https://css-tricks.com/prefetching-preloading-prebrowsing/) 와 CSS 링크 / script 태그를 렌더링된 HTML에 자동으로 삽입할 수 있습니다. + +두가지 장점이 있습니다. + +1. 생성된 파일 이름에 해시가 있을 때 올바른 에셋 URL을 삽입하기 위해 `html-webpack-plugin`를 대체할 수 있습니다. +2. webpack의 주문형 코드 분할 기능을 활용하는 번들을 렌더링할 때 최적의 청크를 프리로드/프리페치하고 클라이언트에 폭포수 요청을 피하기 위해 필요한 비동기 청크에 `` 태그를 지능적으로 삽입할 수 있습니다. 이는 TTI(첫 작동까지의 시간)을 개선합니다. + +클라이언트 매니페스트를 사용하려면 클라이언트 설정은 아래와 같아야 합니다. + +```js +const webpack = require('webpack') +const merge = require('webpack-merge') +const baseConfig = require('./webpack.base.config.js') +const VueSSRClientPlugin = require('vue-server-renderer/client-plugin') +module.exports = merge(baseConfig, { + entry: '/path/to/entry-client.js', + plugins: [ + // Important: this splits the webpack runtime into a leading chunk + // so that async chunks can be injected right after it. + // this also enables better caching for your app/vendor code. + new webpack.optimize.CommonsChunkPlugin({ + name: "manifest", + minChunks: Infinity + }), + // This plugins generates `vue-ssr-client-manifest.json` in the + // output directory. + new VueSSRClientPlugin() + ] +}) +``` + +그런 다음 생성한 클라이언트 매니페스트를 페이지 템플릿과 함께 사용합니다. + +```js +const { createBundleRenderer } = require('vue-server-renderer') +const template = require('fs').readFileSync('/path/to/template.html', 'utf-8') +const serverBundle = require('/path/to/vue-ssr-server-bundle.json') +const clientManifest = require('/path/to/vue-ssr-client-manifest.json') +const renderer = createBundleRenderer(serverBundle, { + template, + clientManifest +}) +``` + +이 설정을 사용하면 코드 분할을 사용하는 빌드의 서버렌더링된 HTML이 다음과 같이 표시됩니다.(전체가 자동으로 주입됩니다) + +```html + + + + + + + + + + + +