diff --git a/es/api/components-nuxt-child.md b/es/api/components-nuxt-child.md new file mode 100644 index 000000000..5cdb900d9 --- /dev/null +++ b/es/api/components-nuxt-child.md @@ -0,0 +1,48 @@ +--- +title: "API: The Component" +description: Display the current page +--- + +# The <nuxt-child> Component + +> This component is used for displaying the children components in a [nested route](/guide/routing#nested-routes). + +Example: + +```bash +-| pages/ +---| parent/ +------| child.vue +---| parent.vue +``` + +This file tree will generate these routes: +```js +[ + { + path: '/parent', + component: '~pages/parent.vue', + name: 'parent', + children: [ + { + path: 'child', + component: '~pages/parent/child.vue', + name: 'parent-child' + } + ] + } +] +``` + +To display the `child.vue` component, I have to insert `` inside `pages/parent.vue`: + +```html + +``` + +To see an example, take a look at the [nested-routes example](/examples/nested-routes). diff --git a/es/api/components-nuxt-link.md b/es/api/components-nuxt-link.md new file mode 100644 index 000000000..910a18504 --- /dev/null +++ b/es/api/components-nuxt-link.md @@ -0,0 +1,23 @@ +--- +title: "API: The Component" +description: Link the pages between them with nuxt-link. +--- + +# The <nuxt-link> Component + +> This component is used to link the page components between them. + +At the moment, `` is the same as [``](https://router.vuejs.org/en/api/router-link.html), so we recommend you to see how to use it on the [vue-router documentation](https://router.vuejs.org/en/api/router-link.html). + +Example (`pages/index.vue`): + +```html + +``` + +In the future, we will add features to the nuxt-link component, like pre-fetching on the background for improving the responsiveness of nuxt.js applications. diff --git a/es/api/components-nuxt.md b/es/api/components-nuxt.md new file mode 100644 index 000000000..7f1f0a7aa --- /dev/null +++ b/es/api/components-nuxt.md @@ -0,0 +1,22 @@ +--- +title: "API: The Component" +description: Display the page components inside a layout. +--- + +# The <nuxt> Component + +> This component is used only in [layouts](/guide/views#layouts) to display the page components. + +Example (`layouts/default.vue`): + +```html + +``` + +To see an example, take a look at the [layouts example](/examples/layouts). diff --git a/es/api/configuration-build.md b/es/api/configuration-build.md new file mode 100644 index 000000000..4c8b152d7 --- /dev/null +++ b/es/api/configuration-build.md @@ -0,0 +1,241 @@ +--- +title: "API: The build Property" +description: Nuxt.js lets you customize the webpack configuration for building your web application as you want. +--- + +# The build Property + +> Nuxt.js lets you customize the webpack configuration for building your web application as you want. + +## analyze + +> Nuxt.js use [webpack-bundle-analyzer](https://github.com/th0r/webpack-bundle-analyzer) to let you visualize your bundles and how to optimize them. + +- Type: `Boolean` or `Object` +- Default: `false` + +If an object, see available properties [here](https://github.com/th0r/webpack-bundle-analyzer#as-plugin). + +Example (`nuxt.config.js`): +```js +module.exports = { + build: { + analyze: true + // or + analyze: { + analyzerMode: 'static' + } + } +} +``` + +

**INFO:** You can use the command `nuxt build --analyzer` or `nuxt build -a` to build your application and launch the bundle analyzer on [http://localhost:8888](http://localhost:8888)

+ +## babel + +- Type: `Object` + +> Customize babel configuration for JS and Vue files. + +Default: +```js +{ + presets: ['vue-app'] +} +``` + +Example (`nuxt.config.js`): +```js +module.exports = { + build: { + babel: { + presets: ['es2015', 'stage-0'] + } + } +} +``` + +## extend + +- Type: `Function` + +> Extend the webpack configuration manually for the client & server bundles. + +The extend is called twice, one time for the server bundle, and one time for the client bundle. The arguments of the method are: +1. Webpack config object +2. Object with the folowing keys (all boolean): `dev`, `isClient`, `isServer` + +Example (`nuxt.config.js`): +```js +module.exports = { + build: { + extend (config, { isClient }) { + // Extend only webpack config for client-bundle + if (isClient) { + config.devtool = 'eval-source-map' + } + } + } +} +``` + +If you want to see more about our default webpack configuration, take a look at our [webpack directory](https://github.com/nuxt/nuxt.js/tree/master/lib/webpack). + +## filenames + +- Type: `Object` + +> Customize bundle filenames + +Default: +```js +{ + css: 'style.[hash].css', + vendor: 'vendor.bundle.[hash].js', + app: 'nuxt.bundle.[chunkhash].js' +} +``` + +Example (`nuxt.config.js`): +```js +module.exports = { + build: { + filenames: { + css: 'app.[hash].css', + vendor: 'vendor.[hash].js', + app: 'app.[chunkhash].js' + } + } +} +``` + +## loaders + +- Type: `Array` + - Items: `Object` + +> Cusomize webpack loaders + +Default: +```js +[ + { + test: /\.(png|jpe?g|gif|svg)$/, + loader: 'url-loader', + query: { + limit: 1000, // 1KO + name: 'img/[name].[hash:7].[ext]' + } + }, + { + test: /\.(woff2?|eot|ttf|otf)(\?.*)?$/, + loader: 'url-loader', + query: { + limit: 1000, // 1 KO + name: 'fonts/[name].[hash:7].[ext]' + } + } +] +``` + +Example (`nuxt.config.js`): +```js +module.exports = { + build: { + loaders: [ + { + test: /\.(png|jpe?g|gif|svg)$/, + loader: 'url-loader', + query: { + limit: 10000, // 10KO + name: 'img/[name].[hash].[ext]' + } + } + ] + } +} +``` + +

When the loaders are defined in the `nuxt.config.js`, the default loaders will be overwritten.

+ +## plugins + +- Type: `Array` +- Default: `[]` + +> Add Webpack plugins + +Example (`nuxt.config.js`): +```js +const webpack = require('webpack') + +module.exports = { + build: { + plugins: [ + new webpack.DefinePlugin({ + 'process.VERSION': require('./package.json').version + }) + ] + } +} +``` + +## postcss + +- **Type:** `Array` + +> Customize [postcss](https://github.com/postcss/postcss) options + +Default: +```js +[ + require('autoprefixer')({ + browsers: ['last 3 versions'] + }) +] +``` + +Example (`nuxt.config.js`): +```js +module.exports = { + build: { + postcss: [ + require('postcss-nested')(), + require('postcss-responsive-type')(), + require('postcss-hexrgba')(), + require('autoprefixer')({ + browsers: ['last 3 versions'] + }) + ] + } +} +``` + +## vendor + +> Nuxt.js lets you add modules inside the `vendor.bundle.js` file generated to reduce the size of the app bundle. It's really useful when using external modules (like `axios` for example) + +- **Type:** `Array` + - **Items:** `String` + +To add a module/file inside the vendor bundle, add the `build.vendor` key inside `nuxt.config.js`: + +```js +module.exports = { + build: { + vendor: ['axios'] + } +} +``` + +You can also give a path to a file, like a custom lib you created: +```js +module.exports = { + build: { + vendor: [ + 'axios', + '~plugins/my-lib.js' + ] + } +} +``` diff --git a/es/api/configuration-cache.md b/es/api/configuration-cache.md new file mode 100644 index 000000000..5db7a1db0 --- /dev/null +++ b/es/api/configuration-cache.md @@ -0,0 +1,33 @@ +--- +title: "API: The cache Property" +description: Nuxt.js use lru-cache to allow cached components for better render performances +--- + +# The cache Property + +> Nuxt.js use [lru-cache](https://github.com/isaacs/node-lru-cache) to allow cached components for better render performances + +## Usage + +- **Type:** `Boolean` or `Object` (Default: `false`) + +If an object, see [lru-cache options](https://github.com/isaacs/node-lru-cache#options). + +Use the `cache` key in your `nuxt.config.js`: +```js +module.exports = { + cache: true + // or + cache: { + max: 1000, + maxAge: 900000 + } +} +``` + +If `cache` is set to `true` the default keys given are: + +| key | Optional? | Type | Default | definition | +|------|------------|-----|---------|------------| +| `max` | Optional | Integer | 1000 | The maximum size of the cached components, when the 1001 is added, the first one added will be removed from the cache to let space for the new one. | +| `maxAge` | Optional | Integer | 900000 | Maximum age in ms, default to 15 minutes. | diff --git a/es/api/configuration-css.md b/es/api/configuration-css.md new file mode 100644 index 000000000..34071b0ed --- /dev/null +++ b/es/api/configuration-css.md @@ -0,0 +1,34 @@ +--- +title: "API: The css Property" +description: Nuxt.js lets you define the CSS files/modules/libraries you want to set globally (included in every pages). +--- + +# The css Property + +> Nuxt.js lets you define the CSS files/modules/libraries you want to set globally (included in every pages). + +- **Type:** `Array` + - **Items:** `String` or `Object` + +If the item is an object, the properties are: +- src: `String` (path of the file) +- lang: `String` ([pre-processor used](/faq/pre-processors)) + +In `nuxt.config.js`, add the CSS resources: + +```js +module.exports = { + css: [ + // Load a node.js module + 'hover.css/css/hover-min.css', + // node.js module but we specify the pre-processor + { src: 'bulma', lang: 'sass' }, + // Css file in the project + '~assets/css/main.css', + // Sass file in the project + { src: '~assets/css/main.scss', lang: 'scss' } // scss instead of sass + ] +} +``` + +

**In production**, all CSS will be minified and extracted in a file named `styles.css` and added in the `` of the page.

diff --git a/es/api/configuration-dev.md b/es/api/configuration-dev.md new file mode 100644 index 000000000..4b1342ddd --- /dev/null +++ b/es/api/configuration-dev.md @@ -0,0 +1,63 @@ +--- +title: "API: The dev Property" +description: Define the development or production mode. +--- + +# The dev Property + +- Type: `Boolean` +- Default: `true` + +> Define the development or production mode of nuxt.js + +This property is overwritten by [nuxt commands](/guide/commands): +- `dev` is forced to `true` with `nuxt` +- `dev` is force to `false` with `nuxt build`, `nuxt start` and `nuxt generate` + +This property should be used when using [nuxt.js programmatically](/api/nuxt): + +Example: + +`nuxt.config.js` +```js +module.exports = { + dev: (process.env.NODE_ENV !== 'production') +} +``` + +`server.js` +```js +const Nuxt = require('nuxt') +const app = require('express')() +const port = process.env.PORT || 3000 + +// We instantiate Nuxt.js with the options +let config = require('./nuxt.config.js') +const nuxt = new Nuxt(config) +app.use(nuxt.render) + +// Build only in dev mode +if (config.dev) { + nuxt.build() + .catch((error) => { + console.error(error) + process.exit(1) + }) +} + +// Listen the server +app.listen(port, '0.0.0.0') +console.log('Server listening on localhost:' + port) +``` + +Then in your `package.json`: +```json +{ + "scripts": { + "dev": "node server.js", + "build": "nuxt build", + "start": "cross-env NODE_ENV=production node server.js" + } +} +``` +Note: You'll need to run `npm install --save-dev cross-env` for the above example to work. If you're *not* developing on Windows you can leave cross-env out of your `start` script and set `NODE_ENV` directly. diff --git a/es/api/configuration-env.md b/es/api/configuration-env.md new file mode 100644 index 000000000..12765e988 --- /dev/null +++ b/es/api/configuration-env.md @@ -0,0 +1,41 @@ +--- +title: "API: The env Property" +description: Share environment variables between client and server. +--- + +# The env Property + +- Type: `Object` + +> Nuxt.js lets you create environment variables that will be shared for the client and server-side. + +Example (`nuxt.config.js`): + +```js +module.exports = { + env: { + baseUrl: process.env.BASE_URL || 'http://localhost:3000' + } +} +``` + +This lets me create a `baseUrl` property that will be equal to the `BASE_URL` environment variable if defined, otherwise, equal to `http://localhost:3000`. + +Then, I can access my `baseUrl` variable with 2 ways: +1. Via `process.env.baseUrl` +2. Via `context.baseUrl`, see [context api](/api#context) + +You can use the `env` property for giving public token for example. + +For the example above, we can use it to configure [axios](https://github.com/mzabriskie/axios). + +`plugins/axios.js`: +```js +import axios from 'axios' + +export default axios.create({ + baseURL: process.env.baseUrl +}) +``` + +Then, in your pages, you can import axios like this: `import axios from '~plugins/axios'` diff --git a/es/api/configuration-generate.md b/es/api/configuration-generate.md new file mode 100644 index 000000000..d06585a68 --- /dev/null +++ b/es/api/configuration-generate.md @@ -0,0 +1,125 @@ +--- +title: "API: The generate Property" +description: Configure the generation of your universal web application to a static web application. +--- + +# The generate Property + +- Type: `Object` + +> Configure the generation of your universal web application to a static web application. + +When launching `nuxt generate` or calling `nuxt.generate()`, nuxt.js will use the configuration defined in the `generate` property. + +## dir + +- Type: `String` +- Default: `'dist'` + +Directory name created by `nuxt generate`. + +## routeParams + +- Type: `Object` + - Key: `String` (route path) + - Value: `Array` or `Function` + +When using [dynamic routes](/guide/routing#dynamic-routes), you need to define a mapping of params for each dynamic route to generate. + +Example: + +```bash +-| pages/ +---| index.vue +---| users/ +-----| _id.vue +``` + +The routes generated by nuxt.js are `/` and `/users/:id`. + +If you try to launch `nuxt generate`, the terminal will exit with an error: + +```bash +Could not generate the dynamic route /users/:id, please add the mapping params in nuxt.config.js (generate.routeParams). +``` + +We add the mapping for `/users/:id` in `nuxt.config.js`: +```js +module.exports = { + generate: { + routeParams: { + '/users/:id': [ + { id: 1 }, + { id: 2 }, + { id: 3 } + ] + } + } +} +``` + +Then when we launch `nuxt generate`: +```bash +[nuxt] Generating... +[...] +nuxt:render Rendering url / +154ms +nuxt:render Rendering url /users/1 +12ms +nuxt:render Rendering url /users/2 +33ms +nuxt:render Rendering url /users/3 +7ms +nuxt:generate Generate file: /index.html +21ms +nuxt:generate Generate file: /users/1/index.html +31ms +nuxt:generate Generate file: /users/2/index.html +15ms +nuxt:generate Generate file: /users/3/index.html +23ms +nuxt:generate HTML Files generated in 7.6s +6ms +[nuxt] Generate done +``` + +Great, but what if we have **dynamic params**? +1. Use a `Function` which returns a `Promise` +2. Use a `Function` with a callback(err, params) + +### Function which returns a Promise + +`nuxt.config.js` +```js +import axios from 'axios' + +module.exports = { + generate: { + routeParams: { + '/users/:id': function () { + return axios.get('https://my-api/users') + .then((res) => { + return res.data.map((user) => { + return { id: user.id } + }) + }) + } + } + } +} +``` + +## Function with a callback + +`nuxt.config.js` +```js +import axios from 'axios' + +module.exports = { + generate: { + routeParams: { + '/users/:id': function (callback) { + axios.get('https://my-api/users') + .then((res) => { + var params = res.data.map((user) => { + return { id: user.id } + }) + callback(null, params) + }) + .catch(callback) + } + } + } +} +``` diff --git a/es/api/configuration-head.md b/es/api/configuration-head.md new file mode 100644 index 000000000..3c8e71286 --- /dev/null +++ b/es/api/configuration-head.md @@ -0,0 +1,27 @@ +--- +title: "API: The head Property" +description: Nuxt.js let you define all default meta for your application inside nuxt.config.js. +--- + +# The head Property + +> Nuxt.js let you define all default meta for your application inside `nuxt.config.js`, use the same `head` property: + +- **Type:** `Object` + +```js +module.exports = { + head: { + titleTemplate: '%s - Nuxt.js', + meta: [ + { charset: 'utf-8' }, + { name: 'viewport', content: 'width=device-width, initial-scale=1' }, + { hid: 'description', name: 'description', content: 'Meta description' } + ] + } +} +``` + +To know the list of options you can give to `head`, take a look at [vue-meta documentation](https://github.com/declandewet/vue-meta#recognized-metainfo-properties). + +

INFO: You can also use `head` in the page components and access to the component data through `this`, see [component head property](/api/pages-head).

diff --git a/es/api/configuration-loading.md b/es/api/configuration-loading.md new file mode 100644 index 000000000..a1276936a --- /dev/null +++ b/es/api/configuration-loading.md @@ -0,0 +1,109 @@ +--- +title: "API: The loading Property" +description: Nuxt.js uses it's own component to show a progress bar between the routes. You can customize it, disable it or create your own component. +--- + +# The loading Property + +- Type: `Boolean` or `Object` or `String` + +> Nuxt.js uses it's own component to show a progress bar between the routes. You can customize it, disable it or create your own component. + +## Disable the Progress Bar + +- Type: `Boolean` + +If you don't want to display the progress bar between the routes, simply add `loading: false` in your `nuxt.config.js` file: + +```js +module.exports = { + loading: false +} +``` + +## Customize the Progress Bar + +- Type: `Object` + +List of properties to customize the progress bar. + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `color` | String | `'black'` | CSS color of the progress bar | +| `failedColor` | String | `'red'` | CSS color of the progress bar when an error appended while rendering the route (if `data` or `fetch` sent back an error for example). | +| `height` | String | `'2px'` | Height of the progress bar (used in the `style` property of the progress bar) | +| `duration` | Number | `5000` | In ms, the maximum duration of the progress bar, Nuxt.js assumes that the route will be rendered before 5 seconds. | + +For a blue progress bar with 5px of height, we update the `nuxt.config.js` to the following: + +```js +module.exports = { + loading: { + color: 'blue', + height: '5px' + } +} +``` + +## Use a Custom Loading Component + +- Type: `String` + +You can create your own component that Nuxt.js will call instead of its default component. To do so, you need to give a path to your component in the `loading` option. Then, your component will be called directly by Nuxt.js. + +**Your component has to expose some of theses methods:** + +| Method | Required | Description | +|--------|----------|-------------| +| `start()` | Required | Called when a route changes, this is here where you display your component. | +| `finish()` | Required | Called when a route is loaded (and data fetched), this is here where you hide your component. | +| `fail()` | *Optional* | Called when a route couldn't be loaded (failed to fetch data for example). | +| `increase(num)` | *Optional* | Called during loading the route component, `num` is an Integer < 100. | + +We can create our custom component in `components/loading.vue`: +```html + + + + + +``` + +Then, we update our `nuxt.config.js` to tell Nuxt.js to use our component: + +```js +module.exports = { + loading: '~components/loading.vue' +} +``` diff --git a/es/api/configuration-performance.md b/es/api/configuration-performance.md new file mode 100644 index 000000000..c93bb705c --- /dev/null +++ b/es/api/configuration-performance.md @@ -0,0 +1,48 @@ +--- +title: "API: The performance Property" +description: Configure nuxt.js performance options +--- + +# The performance Property + +> Nuxt.js lets you configure nuxt.js performance options. + +## gzip + +- Type: `Boolean` +- Default: `true` + +In production, nuxt.js will gzip all your assets by using the [compression](https://github.com/expressjs/compression) module. + +If you are using a service like [CloudFare](https://www.cloudflare.com/) which already gzip every response, you can disable this feature in your `nuxt.config.js`: +```js +module.exports = { + performance: { + gzip: false + } +} +``` + +## prefetch + +- Type: `Boolean` +- Default: `true` + +In production, nuxt.js uses the [prefetch](https://www.w3.org/TR/resource-hints/#dfn-prefetch) strategy to pre-fetch the pages bundle that will be required when navigating to the next page. When the user will click on a link, nuxt.js will already have pre-fetched the page and the navigation will fill like instant will keeping the code splitted. + +Example of the `prefetch` feature (in the `` of the page rendered): +```html + + + +``` + +To disable this feature, add this to your `nuxt.config.js`: + +```js +module.exports = { + performance: { + prefetch: false + } +} +``` diff --git a/es/api/configuration-plugins.md b/es/api/configuration-plugins.md new file mode 100644 index 000000000..6998e0082 --- /dev/null +++ b/es/api/configuration-plugins.md @@ -0,0 +1,32 @@ +--- +title: "API: The plugins Property" +description: Use vue.js plugins with the plugins option of nuxt.js. +--- + +# The plugins Property + +- Type: `Array` + - Items: `String` + +> The plugins property lets you add vue.js plugins easily to your main application. + +Example (`nuxt.config.js`): +```js +module.exports = { + plugins: ['~plugins/vue-notifications'] +} +``` + +Then, we need to create a file in `plugins/vue-notifications.js`: +```js +import Vue from 'vue' +import VueNotifications from 'vue-notifications' + +Vue.use(VueNotifications) +``` + +All the paths defined in the `plugins` property will be **imported** before initializing the main application. + +Every time you need to use `Vue.use()`, you should create a file in `plugins/` and add its path to `plugins` in `nuxt.config.js`. + +To learn more how to use the plugins, see the [guide documentation](/guide/plugins#vue-plugins). diff --git a/es/api/configuration-rootdir.md b/es/api/configuration-rootdir.md new file mode 100644 index 000000000..f4570d221 --- /dev/null +++ b/es/api/configuration-rootdir.md @@ -0,0 +1,17 @@ +--- +title: "API: The rootDir Property" +description: Define the workspace of nuxt.js application +--- + +# The rootDir Property + +- Type: `String` +- Default: `process.cwd()` + +> Define the workspace of your nuxt.js application. + +This property is overwritten by [nuxt commands](/guide/commands) and set to the argument of the command (example: `nuxt my-app/` will set the `rootDir` to `my-app/` with its absolute path). + +This property should be used when using [nuxt.js programmatically](/api/nuxt). + +

The downside of this option is that your `node_modules` directory should be inside the `rootDir` folder. If you want to set the path of the application without the node_modules, use the [`srcDir` option](/api/configuration-srcdir).

diff --git a/es/api/configuration-router.md b/es/api/configuration-router.md new file mode 100644 index 000000000..0950cace0 --- /dev/null +++ b/es/api/configuration-router.md @@ -0,0 +1,147 @@ +--- +title: "API: The router Property" +description: The router property lets you customize nuxt.js router. +--- + +# The router Property + +> The router property lets you customize nuxt.js router ([vue-router](https://router.vuejs.org/en/)). + +## base + +- Type: `String` +- Default: `'/'` + +The base URL of the app. For example, if the entire single page application is served under `/app/`, then base should use the value `'/app/'`. + +Example (`nuxt.config.js`): +```js +module.exports = { + router: { + base: '/app/' + } +} +``` + +

When `base` is set, nuxt.js will also add in the document header ``.

+ +> This option is given directly to the vue-router [Router constructor](https://router.vuejs.org/en/api/options.html). + +## linkActiveClass + +- Type: `String` +- Default: `'nuxt-link-active'` + +Globally configure [``](/api/components-nuxt-link) default active class. + +Example (`nuxt.config.js`): +```js +module.exports = { + router: { + linkActiveClass: 'active-link' + } +} +``` + +> This option is given directly to the [vue-router Router constructor](https://router.vuejs.org/en/api/options.html). + +## scrollBehavior + +- Type: `Function` + +The `scrollBehavior` option lets you define a custom behavior for the scroll position between the routes. This method is called every time a page is rendered. + +By default, the scrollBehavior option is set to: +```js +const scrollBehavior = (to, from, savedPosition) => { + // savedPosition is only available for popstate navigations. + if (savedPosition) { + return savedPosition + } else { + let position = {} + // if no children detected + if (to.matched.length < 2) { + // scroll to the top of the page + position = { x: 0, y: 0 } + } + else if (to.matched.some((r) => r.components.default.options.scrollToTop)) { + // if one of the children has scrollToTop option set to true + position = { x: 0, y: 0 } + } + // if link has anchor, scroll to anchor by returning the selector + if (to.hash) { + position = { selector: to.hash } + } + return position + } +} +``` + +Example of forcing the scroll position to the top for every routes: + +`nuxt.config.js` +```js +module.exports = { + router: { + scrollBehavior: function (to, from, savedPosition) { + return { x: 0, y: 0 } + } + } +} +``` + +> This option is given directly to the vue-router [Router constructor](https://router.vuejs.org/en/api/options.html). + +## middleware + +- Type: `String` or `Array` + - Items: `String` + +Set the default(s) middleware for every pages of the application. + +Example: + +`nuxt.config.js` +```js +module.exports = { + router: { + // Run the middleware/user-agent.js on every pages + middleware: 'user-agent' + } +} +``` + +`middleware/user-agent.js` +```js +export default function (context) { + // Add the userAgent property in the context (available in `data` and `fetch`) + context.userAgent = context.isServer ? context.req.headers['user-agent'] : navigator.userAgent +} +``` + +To learn more about the middleware, see the [middleware guide](/guide/routing#middleware). + +## extendRoutes + +- Type: `Function` + +You may want to extend the routes created by nuxt.js. You can do it via the `extendRoutes` option. + +Example of adding a custom route: + +`nuxt.config.js` +```js +module.exports = { + router: { + extendRoutes (routes, resolve) { + routes.push({ + name: 'custom', + path: '*', + component: resolve(__dirname, 'pages/404.vue') + }) + } + } +} +``` + +The schema of the route should respect the [vue-router](https://router.vuejs.org/en/) schema. diff --git a/es/api/configuration-srcdir.md b/es/api/configuration-srcdir.md new file mode 100644 index 000000000..9b23566d0 --- /dev/null +++ b/es/api/configuration-srcdir.md @@ -0,0 +1,32 @@ +--- +title: "API: The srcDir Property" +description: Define the source directory of your nuxt.js application +--- + +# The srcDir Property + +- Type: `String` +- Default: [rootDir value](/api/configuration-rootdir) + +> Define the source directory of your nuxt.js application + +Example (`nuxt.config.js`): + +```js +module.exports = { + srcDir: 'client/' +} +``` + +Then, your application structure can be: +```bash +-| app/ +---| node_modules/ +---| client/ +------| pages/ +------| components/ +---| nuxt.config.js +---| package.json +``` + +This option is useful to have a custom server and using nuxt.js, so all npm dependencies can be regrouped in one `package.json`. diff --git a/es/api/configuration-transition.md b/es/api/configuration-transition.md new file mode 100644 index 000000000..9fa7efc79 --- /dev/null +++ b/es/api/configuration-transition.md @@ -0,0 +1,36 @@ +--- +title: "API: The transition Property" +description: Set the default properties of the pages transitions. +--- + +# The transition Property + +- Type: `String` or `Object` + +> Used to set the default properties of the pages transitions. + +Default: +```js +{ + name: 'page', + mode: 'out-in' +} +``` + +Example (`nuxt.config.js`): + +```js +module.exports = { + transition: 'page' + // or + transition: { + name: 'page', + mode: 'out-in', + beforeEnter (el) { + console.log('Before enter...'); + } + } +} +``` + +The transition key in `nuxt.config.js` is used to set the default properties for the pages transitions. To learn more about the available keys when the `transition` key is an object, see the [pages transition property](/api/pages-transition#object). diff --git a/es/api/index.md b/es/api/index.md new file mode 100644 index 000000000..4fb78c6f5 --- /dev/null +++ b/es/api/index.md @@ -0,0 +1,41 @@ +--- +title: "API: The data Method" +description: Nuxt.js supercharges the data method from vue.js to let you handle async operation before setting the component data. +--- + +# The data Method + +> Nuxt.js *supercharges* the `data` method from vue.js to let you handle async operation before setting the component data. + +- **Type:** `Function` + +`data` is called every time before loading the component (**only for pages components**). It can be called from the server-side or before navigating to the corresponding route. This method receives the **context** as the first argument, you can use it to fetch some data and return the component data. + +```js +export default { + data (context) { + return { foo: 'bar' } + } +} +``` + +
You do **NOT** have access of the component instance through `this` inside `data` because it is called **before initiating** the component.
+ +## Context + +List of all the available keys in `context`: + +| Key | Type | Available | Description | +|-----|------|--------------|-------------| +| `isClient` | Boolean | Client & Server | Boolean to let you know if you're actually renderer from the client-side | +| `isServer` | Boolean | Client & Server | Boolean to let you know if you're actually renderer from the server-side | +| `isDev` | Boolean | Client & Server | Boolean to let you know if you're in dev mode, can be useful for caching some data in production | +| `route` | [vue-router route](https://router.vuejs.org/en/api/route-object.html) | Client & Server | `vue-router` route instance. | +| `store` | [vuex store](http://vuex.vuejs.org/en/api.html#vuexstore-instance-properties) | Client & Server | `Vuex.Store` instance. **Available only if the [vuex store](/guide/vuex-store) is set.** | +| `env` | Object | Client & Server | Environment variables set in `nuxt.config.js`, see [env api](/api/configuration-env) | +| `params` | Object | Client & Server | Alias of route.params | +| `query` | Object | Client & Server | Alias of route.query | +| `req` | [http.Request](https://nodejs.org/api/http.html#http_class_http_incomingmessage) | Server | Request from the node.js server. If nuxt is used as a middleware, the req object might be different depending of the framework you're using. *Not available via `nuxt generate`*. | +| `res` | [http.Response](https://nodejs.org/api/http.html#http_class_http_serverresponse) | Server | Response from the node.js server. If nuxt is used as a middleware, the res object might be different depending of the framework you're using. *Not available via `nuxt generate`*. | +| `redirect` | Function | Client & Server | Use this method to redirect the user to another route, the status code is used on the server-side, default to 302. `redirect([status,] path [, query])` | +| `error` | Function | Client & Server | Use this method to show the error page: `error(params)`. The `params` should have the fields `statusCode` and `message`. | diff --git a/es/api/menu.json b/es/api/menu.json new file mode 100644 index 000000000..ac57cafad --- /dev/null +++ b/es/api/menu.json @@ -0,0 +1,103 @@ +[ + { + "title": "Pages", + "links": [ + { "name": "data", "to": "/" }, + { "name": "fetch", "to": "/pages-fetch" }, + { "name": "head", "to": "/pages-head" }, + { "name": "layout", "to": "/pages-layout" }, + { "name": "middleware", "to": "/pages-middleware" }, + { "name": "scrollToTop", "to": "/pages-scrolltotop" }, + { + "name": "transition", "to": "/pages-transition", + "contents": [ + { "name": "String", "to": "#string" }, + { "name": "Object", "to": "#object" }, + { "name": "Function", "to": "#function" } + ] + }, + { "name": "validate", "to": "/pages-validate" } + ] + }, + { + "title": "Components", + "links": [ + { "name": "nuxt", "to": "/components-nuxt" }, + { "name": "nuxt-child", "to": "/components-nuxt-child" }, + { "name": "nuxt-link", "to": "/components-nuxt-link" } + ] + }, + { + "title": "Configuration", + "links": [ + { + "name": "build", + "to": "/configuration-build", + "contents": [ + { "name": "analyze", "to": "#analyze" }, + { "name": "babel", "to": "#babel" }, + { "name": "extend", "to": "#extend" }, + { "name": "filenames", "to": "#filenames" }, + { "name": "loaders", "to": "#loaders" }, + { "name": "plugins", "to": "#plugins" }, + { "name": "postcss", "to": "#postcss" }, + { "name": "vendor", "to": "#vendor" } + ] + }, + { "name": "cache", "to": "/configuration-cache" }, + { "name": "css", "to": "/configuration-css" }, + { "name": "dev", "to": "/configuration-dev" }, + { "name": "env", "to": "/configuration-env" }, + { + "name": "generate", + "to": "/configuration-generate", + "contents": [ + { "name": "dir", "to": "#dir" }, + { "name": "routeParams", "to": "#routeparams" } + ] + }, + { "name": "head", "to": "/configuration-head" }, + { + "name": "loading", + "to": "/configuration-loading", + "contents": [ + { "name": "Disable the Progress Bar", "to": "#disable-the-progress-bar" }, + { "name": "Customize the Progress Bar", "to": "#customize-the-progress-bar" }, + { "name": "Use a Custom Loading Component", "to": "#use-a-custom-loading-component" } + ] + }, + { + "name": "performance", + "to": "/configuration-performance", + "contents": [ + { "name": "gzip", "to": "#gzip" }, + { "name": "prefetch", "to": "#prefetch" } + ] + }, + { "name": "plugins", "to": "/configuration-plugins" }, + { "name": "rootDir", "to": "/configuration-rootdir" }, + { + "name": "router", + "to": "/configuration-router", + "contents": [ + { "name": "base", "to": "#base" }, + { "name": "linkActiveClass", "to": "#linkactiveclass" }, + { "name": "scrollBehavior", "to": "#scrollbehavior" }, + { "name": "middleware", "to": "#middleware" }, + { "name": "extendRoutes", "to": "#extendroutes" } + ] + }, + { "name": "srcDir", "to": "/configuration-srcdir" }, + { "name": "transition", "to": "/configuration-transition" } + ] + }, + { + "title": "Nuxt Module", + "links": [ + { "name": "Usage", "to": "/nuxt" }, + { "name": "render", "to": "/nuxt-render" }, + { "name": "renderRoute", "to": "/nuxt-render-route" }, + { "name": "renderAndGetWindow", "to": "/nuxt-render-and-get-window" } + ] + } +] diff --git a/es/api/nuxt-render-and-get-window.md b/es/api/nuxt-render-and-get-window.md new file mode 100644 index 000000000..b8c4368f9 --- /dev/null +++ b/es/api/nuxt-render-and-get-window.md @@ -0,0 +1,35 @@ +--- +title: "API: nuxt.renderAndGetWindow(url, options)" +description: Get the window from a given url of a nuxt.js application. +--- + +# nuxt.renderAndGetWindow(url, options = {}) + +- Type: `Function` +- Argument: `String` + 1. `String`: url to render + 2. *Optional*, `Object`: options + - virtualConsole: `Boolean` (default: `true`) +- Returns: `Promise` + - Returns: `window` + +> Get the window from a given url of a nuxt.js application. + +

This method is made for [test purposes](guide/development-tools#end-to-end-testing).

+ +To use this function, you have to install `jsdom`: +```bash +npm install --save-dev jsdom +``` + +Example: +```js +const Nuxt = require('nuxt') +const nuxt = new Nuxt() + +nuxt.renderAndGetWindow('http://localhost:3000') +.then((window) => { + // Display the head + console.log(window.document.title) +}) +``` diff --git a/es/api/nuxt-render-route.md b/es/api/nuxt-render-route.md new file mode 100644 index 000000000..019a8c65e --- /dev/null +++ b/es/api/nuxt-render-route.md @@ -0,0 +1,43 @@ +--- +title: "API: nuxt.renderRoute(route, context)" +description: Render a specific route with a given context. +--- + +# nuxt.renderRoute(route, context = {}) + +- Type: `Function` +- Arguments: + 1. `String`, route to render + 2. *Optional*, `Object`, context given, available keys: `req` & `res` +- Returns: `Promise` + - `html`: `String` + - `error`: `null` or `Object` + - `redirected`: `false` or `Object` + +> Render a specific route with a given context. + +This method should be used mostly for [test purposes](guide/development-tools#end-to-end-testing) as well with [nuxt.renderAndGetWindow](/api/nuxt-render-and-get-window). + +<p class="Alert Alert--info">`nuxt.renderRoute` should be executed after the build process in production mode (dev: false).</p> + +Example: +```js +const Nuxt = require('nuxt') +let config = require('./nuxt.config.js') +config.dev = false +const nuxt = new Nuxt(config) + +nuxt.build() +.then(() => { + return nuxt.renderRoute('/') +}) +.then(({ html, error, redirected }) => { + // html will be always a string + + // error not null when the error layout is displayed, the error format is: + // { statusCode: 500, message: 'My error message' } + + // redirected is not false when redirect() has been used in data() or fetch() + // { path: '/other-path', query: {}, status: 302 } +}) +``` diff --git a/es/api/nuxt-render.md b/es/api/nuxt-render.md new file mode 100644 index 000000000..b6eac5d7a --- /dev/null +++ b/es/api/nuxt-render.md @@ -0,0 +1,45 @@ +--- +title: "API: nuxt.render(req, res)" +description: You can use Nuxt.js as a middleware for your node.js server. +--- + +# nuxt.render(req, res) + +- Type: `Function` +- Arguments: + 1. [Request](https://nodejs.org/api/http.html#http_class_http_incomingmessage) + 2. [Response](https://nodejs.org/api/http.html#http_class_http_serverresponse) +- Returns: `Promise` + +> You can use nuxt.js as a middleware with `nuxt.render` for your node.js server. + +Example with [Express.js](https://github.com/expressjs/express): +```js +const Nuxt = require('nuxt') +const app = require('express')() +const isProd = (process.env.NODE_ENV === 'production') +const port = process.env.PORT || 3000 + +// We instantiate nuxt.js with the options +let config = require('./nuxt.config.js') +config.dev = !isProd +const nuxt = new Nuxt(config) + +// Render every route with nuxt.js +app.use(nuxt.render) + +// Build only in dev mode with hot-reloading +if (config.dev) { + nuxt.build() + .catch((error) => { + console.error(error) + process.exit(1) + }) +} + +// Listen the server +app.listen(port, '0.0.0.0') +console.log('Server listening on localhost:' + port) +``` + +<p class="Alert">It's recommended to call **nuxt.render** at the end of your middlewares since it will handle the rendering of your web application and won't call next()</p> diff --git a/es/api/nuxt.md b/es/api/nuxt.md new file mode 100644 index 000000000..4ff4de310 --- /dev/null +++ b/es/api/nuxt.md @@ -0,0 +1,38 @@ +--- +title: "API: Nuxt(options)" +description: You can use nuxt.js programmatically to use it as a middleware giving you the freedom of creating your own server for rendering your web applications. +--- + +# Using Nuxt.js Programmatically + +You might want to use your own server with your middleware and your API. That's why you can use Nuxt.js programmatically. +Nuxt.js is built on the top of ES2015, which makes the code more enjoyable and cleaner to read. It doesn't make use of any transpilers and depends upon Core V8 implemented features. For these reasons, Nuxt.js targets Node.js `4.0` or higher. + +You can require Nuxt.js like this: +```js +const Nuxt = require('nuxt') +``` + +## Nuxt(options) + +To see the list of options to give to Nuxt.js, see the configuration section. + +```js +const options = {} + +const nuxt = new Nuxt(options) +nuxt.build() +.then(() => { + // We can use nuxt.render(req, res) or nuxt.renderRoute(route, context) +}) +``` + +You can take a look at the [nuxt-express](https://github.com/nuxt/express) and [adonuxt](https://github.com/nuxt/adonuxt) starters to start quickly. + +### Debug logs + +If you want to display nuxt.js logs, you can add to the top of your file: + +```js +process.env.DEBUG = 'nuxt:*' +``` diff --git a/es/api/pages-fetch.md b/es/api/pages-fetch.md new file mode 100644 index 000000000..aa8cf8c72 --- /dev/null +++ b/es/api/pages-fetch.md @@ -0,0 +1,49 @@ +--- +title: "API: The fetch Method" +description: The fetch method is used to fill the store before rendering the page, it's like the data method except it doesn't set the component data. +--- + +# The fetch Method + +> The fetch method is used to fill the store before rendering the page, it's like the data method except it doesn't set the component data. + +- **Type:** `Function` + +The `fetch` method, *if set*, is called every time before loading the component (**only for pages components**). It can be called from the server-side or before navigating to the corresponding route. + +The `fetch` method receives [the context](/api#context) as the first argument, we can use it to fetch some data and fill the store. To make the fetch method asynchronous, **return a Promise**, nuxt.js will wait for the promise to be resolved before rendering the Component. + +Example of `pages/index.vue`: +```html +<template> + <h1>Stars: {{ $store.state.stars }}</h1> +</template> + +<script> +export default { + fetch ({ store, params }) { + return axios.get('http://my-api/stars') + .then((res) => { + store.commit('setStars', res.data) + }) + } +} +</script> +``` + +You can also use async/await to make your code cleaner: + +```html +<template> + <h1>Stars: {{ $store.state.stars }}</h1> +</template> + +<script> +export default { + async fetch ({ store, params }) { + let { data } = await axios.get('http://my-api/stars') + store.commit('setStars', data) + } +} +</script> +``` diff --git a/es/api/pages-head.md b/es/api/pages-head.md new file mode 100644 index 000000000..7df5436d6 --- /dev/null +++ b/es/api/pages-head.md @@ -0,0 +1,40 @@ +--- +title: "API: The head Method" +description: Nuxt.js uses vue-meta to update the `headers` and `html attributes` of your application. +--- + +# The head Method + +> Nuxt.js uses [vue-meta](https://github.com/declandewet/vue-meta) to update the `headers` and `html attributes` of your application. + +- **Type:** `Object` or `Function` + +Use the `head` method to set the HTML Head tags for the current page. + +Your component data are available with `this` in the `head` method, you can use set custom meta tags with the page data. + +```html +<template> + <h1>{{ title }}</h1> +</template> + +<script> +export default { + data () { + return { + title: 'Hello World!' + } + }, + head () { + return { + title: this.title, + meta: [ + { hid: 'description', name: 'description', content: 'My custom description' } + ] + } + } +} +</script> +``` + +<p class="Alert">To avoid any duplication when used in child component, please give a unique identifier with the `hid` key, please [read more about it](https://github.com/declandewet/vue-meta#lists-of-tags).</p> diff --git a/es/api/pages-layout.md b/es/api/pages-layout.md new file mode 100644 index 000000000..5d28db248 --- /dev/null +++ b/es/api/pages-layout.md @@ -0,0 +1,24 @@ +--- +title: "API: The layout Property" +description: Every file (first level) in the layouts directory will create a custom layout accessible with the layout property in the page component. +--- + +# The layout Property + +> Every file (first level) in the layouts directory will create a custom layout accessible with the layout property in the page component. + +- **Type:** `String` (default: `'default'`) + +Use the `layout` key in your pages components to define which layout to use: + +```js +export default { + layout: 'blog' +} +``` + +In this example, Nuxt.js will include the `layouts/blog.vue` file as a layout for this page component. + +Check the [demonstration video](https://www.youtube.com/watch?v=YOKnSTp7d38) to see it in action. + +To understand how the layouts work with nuxt.js, take a look at the [layout documentation](/guide/views#layouts). diff --git a/es/api/pages-middleware.md b/es/api/pages-middleware.md new file mode 100644 index 000000000..45c8155cc --- /dev/null +++ b/es/api/pages-middleware.md @@ -0,0 +1,38 @@ +--- +title: "API: The middleware Property" +description: Set the middleware for a specific page of the application. +--- + +# The middleware Property + +- Type: `String` or `Array` + - Items: `String` + +Set the middleware for a specific page of the application. + +Example: + +`pages/secret.vue` +```html +<template> + <h1>Secret page</h1> +</template> + +<script> +export default { + middleware: 'authenticated' +} +</script> +``` + +`middleware/authenticated.js` +```js +export default function ({ store, redirect }) { + // If the user is not authenticated + if (!store.state.authenticated) { + return redirect('/login') + } +} +``` + +To learn more about the middleware, see the [middleware guide](/guide/routing#middleware). diff --git a/es/api/pages-scrolltotop.md b/es/api/pages-scrolltotop.md new file mode 100644 index 000000000..b07b319bd --- /dev/null +++ b/es/api/pages-scrolltotop.md @@ -0,0 +1,26 @@ +--- +title: "API: The scrollToTop Property" +description: The scrollToTop property lets you tell nuxt.js to scroll to the top before rendering the page. +--- + +# The scrollToTop Property + +> The scrollToTop property lets you tell nuxt.js to scroll to the top before rendering the page. + +- **Type:** `Boolean` (default: `false`) + +By default, nuxt.js scroll to the top when you go to another page, but with children routes, nuxt.js keep the scroll position, if you want to tell nuxt.js to scroll to the top when rendering your child route, set `scrollToTop: true`: + +```html +<template> + <h1>My child component</h1> +</template> + +<script> +export default { + scrollToTop: true +} +</script> +``` + +If you want to overwrite the default scroll behavior of nuxt.js, take a look at the [scrollBehavior option](/api/configuration-router#scrollBehavior). diff --git a/es/api/pages-transition.md b/es/api/pages-transition.md new file mode 100644 index 000000000..085761cf0 --- /dev/null +++ b/es/api/pages-transition.md @@ -0,0 +1,105 @@ +--- +title: "API: The transition Property" +description: Nuxt.js uses the transition component to let you create amazing transitions/animations between your pages. +--- + +# The transition Property + +> Nuxt.js uses the [<transition>](http://vuejs.org/v2/guide/transitions.html#Transitioning-Single-Elements-Components) component to let you create amazing transitions/animations between your pages. + +- **Type:** `String` or `Object` or `Function` + +To define a custom transition for a specific route, simply add the `transition` key to the page component. + +```js +export default { + // Can be a String + transition: '' + // Or an Object + transition: {} + // or a Function + transition (to, from) {} +} +``` + +## String + +If the `transition` key is set as a string, it will be used as the `transition.name`. + +```js +export default { + transition: 'test' +} +``` + +Nuxt.js will use these settings to set the component as follows: + +```html +<transition name="test"> +``` + +## Object + +If the `transition` key is set as an object: + +```js +export default { + transition: { + name: 'test', + mode: 'out-in' + } +} +``` + +Nuxt.js will use these settings to set the component as follows: + +```html +<transition name="test" mode="out-in"> +``` + +The following properties that the `transition` object can have: + +| key | Type | Default | definition | +|------|------|---------|-----------| +| `name` | String | `"page"` | The transition name applied on all the routes transitions. | +| `mode` | String | `"out-in"` | The transition mode applied on all routes, see [Vue.js documentation](http://vuejs.org/v2/guide/transitions.html#Transition-Modes). | +| `css` | Boolean | `true` | Whether to apply CSS transition classes. Defaults to true. If set to false, will only trigger JavaScript hooks registered via component events. | +| `type` | String | `n/a` | Specify the type of transition events to wait for to determine transition end timing. Available values are "transition" and "animation". By default, it will automatically detect the type that has a longer duration. | +| `enterClass` | String | `n/a` | The starting state of the transition class. See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | +| `enterToClass` | String | `n/a` | The ending state for the transition. See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | +| `enterActiveClass` | String | `n/a` | The class applied across the entire transition duration. See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | +| `leaveClass` | String | `n/a` | The starting state of the transition class. See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | +| `leaveToClass` | String | `n/a` | The ending state for the transition. See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | +| `leaveActiveClass` | String | `n/a` | The class applied across the entire transition duration. See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | + + +You can also define methods in the `transition`, these are for the [JavaScript hooks](https://vuejs.org/v2/guide/transitions.html#JavaScript-Hooks): + +- beforeEnter(el) +- enter(el, done) +- afterEnter(el) +- enterCancelled(el) +- beforeLeave(el) +- leave(el, done) +- afterLeave(el) +- leaveCancelled(el) + +*Note: it’s also a good idea to explicitly add `css: false` for JavaScript-only transitions so that Vue can skip the CSS detection. This also prevents CSS rules from accidentally interfering with the transition.* + +## Function + +If the `transition` key is set as a function: + +```js +export default { + transition (to, from) { + if (!from) return 'slide-left' + return +to.query.page < +from.query.page ? 'slide-right' : 'slide-left' + } +} +``` + +Transitions applied on navigation: +- `/` to `/posts` => `slide-left` +- `/posts` to `/posts?page=3` => `slide-left` +- `/posts?page=3` to `/posts?page=2` => `slide-right` diff --git a/es/api/pages-validate.md b/es/api/pages-validate.md new file mode 100644 index 000000000..9ed52230d --- /dev/null +++ b/es/api/pages-validate.md @@ -0,0 +1,30 @@ +--- +title: "API: The validate Method" +description: Nuxt.js lets you define a validator method inside your dynamic route component. +--- + +# The validate Method + +> Nuxt.js lets you define a validator method inside your dynamic route component. + +- **Type:** `Function` + +```js +validate({ params, query }) { + return true // if the params are valid + return false // will stop Nuxt.js to render the route and display the error page +} +``` + +Nuxt.js lets you define a validator method inside your dynamic route component (In this example: `pages/users/_id.vue`). + +If the validate method does not return `true`, Nuxt.js will automatically load the 404 error page. + +```js +export default { + validate ({ params }) { + // Must be a number + return /^\d+$/.test(params.id) + } +} +``` diff --git a/es/examples/async-data.md b/es/examples/async-data.md new file mode 100644 index 000000000..0fa258040 --- /dev/null +++ b/es/examples/async-data.md @@ -0,0 +1,6 @@ +--- +title: Async Data +description: Async Data example with Nuxt.js +github: async-data +documentation: /guide/async-data +--- diff --git a/es/examples/auth-routes.md b/es/examples/auth-routes.md new file mode 100644 index 000000000..a77bc089e --- /dev/null +++ b/es/examples/auth-routes.md @@ -0,0 +1,216 @@ +--- +title: Auth Routes +description: Authenticated routes example with Nuxt.js +github: auth-routes +livedemo: https://nuxt-auth-routes.gomix.me +liveedit: https://gomix.com/#!/project/nuxt-auth-routes +--- + +# Documentation + +> Nuxt.js can be used to create authenticated routes easily. + +## Using Express and Sessions + +To add the sessions feature in our application, we will use `express` and `express-session`, for this, we need to use Nuxt.js programmatically. + +First, we install the dependencies: +```bash +yarn add express express-session body-parser whatwg-fetch +``` + +*We will talk about `whatwg-fetch` later.* + +Then we create our `server.js`: +```js +const Nuxt = require('nuxt') +const bodyParser = require('body-parser') +const session = require('express-session') +const app = require('express')() + +// Body parser, to access req.body +app.use(bodyParser.json()) + +// Sessions to create req.session +app.use(session({ + secret: 'super-secret-key', + resave: false, + saveUninitialized: false, + cookie: { maxAge: 60000 } +})) + +// POST /api/login to log in the user and add him to the req.session.authUser +app.post('/api/login', function (req, res) { + if (req.body.username === 'demo' && req.body.password === 'demo') { + req.session.authUser = { username: 'demo' } + return res.json({ username: 'demo' }) + } + res.status(401).json({ error: 'Bad credentials' }) +}) + +// POST /api/logout to log out the user and remove it from the req.session +app.post('/api/logout', function (req, res) { + delete req.session.authUser + res.json({ ok: true }) +}) + +// We instantiate Nuxt.js with the options +const isProd = process.env.NODE_ENV === 'production' +const nuxt = new Nuxt({ dev: !isProd }) +// No build in production +const promise = (isProd ? Promise.resolve() : nuxt.build()) +promise.then(() => { + app.use(nuxt.render) + app.listen(3000) + console.log('Server is listening on http://localhost:3000') +}) +.catch((error) => { + console.error(error) + process.exit(1) +}) +``` + +And we update our `package.json` scripts: +```json +// ... +"scripts": { + "dev": "node server.js", + "build": "nuxt build", + "start": "cross-env NODE_ENV=production node server.js" +} +// ... +``` +Note: You'll need to run `npm install --save-dev cross-env` for the above example to work. If you're *not* developing on Windows you can leave cross-env out of your `start` script and set `NODE_ENV` directly. + +## Using the store + +We need a global state to let our application know if the user is connected **across the pages**. + +To let Nuxt.js use Vuex, we create a `store/index.js` file: + +```js +import Vue from 'vue' +import Vuex from 'vuex' + +Vue.use(Vuex) + +// Polyfill for window.fetch() +require('whatwg-fetch') + +const store = new Vuex.Store({ + + state: { + authUser: null + }, + + mutations: { + SET_USER: function (state, user) { + state.authUser = user + } + }, + + actions: { + // ... + } + +}) + +export default store +``` + +1. We import `Vue` and `Vuex` (included in Nuxt.js) and we tell Vue to use Vuex to let us use `$store` in our components +2. We `require('whatwg-fetch')` to polyfill the `fetch()` method across all browsers (see [fetch repo](https://github.com/github/fetch)) +3. We create our `SET_USER` mutation which will set the `state.authUser` to the connected user +4. We export our store instance to Nuxt.js can inject it to our main application + +### nuxtServerInit() action + +Nuxt.js will call a specific action called `nuxtServerInit` with the context in argument, so when the app will be loaded, the store will be already filled with some data we can get from the server. + +In our `store/index.js`, we can add the `nuxtServerInit` action: +```js +nuxtServerInit ({ commit }, { req }) { + if (req.session && req.session.authUser) { + commit('SET_USER', req.session.authUser) + } +} +``` + +To make the data method asynchronous, nuxt.js offers you different ways, choose the one you're the most familiar with: + +1. returning a `Promise`, nuxt.js will wait for the promise to be resolved before rendering the component. +2. Using the [async/await proposal](https://github.com/lukehoban/ecmascript-asyncawait) ([learn more about it](https://zeit.co/blog/async-and-await)) + +### login() action + +We add a `login` action which will be called from our pages component to log in the user: +```js +login ({ commit }, { username, password }) { + return fetch('/api/login', { + // Send the client cookies to the server + credentials: 'same-origin', + method: 'POST', + headers: { + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + username, + password + }) + }) + .then((res) => { + if (res.status === 401) { + throw new Error('Bad credentials') + } else { + return res.json() + } + }) + .then((authUser) => { + commit('SET_USER', authUser) + }) +} +``` + +### logout() method + +```js +logout ({ commit }) { + return fetch('/api/logout', { + // Send the client cookies to the server + credentials: 'same-origin', + method: 'POST' + }) + .then(() => { + commit('SET_USER', null) + }) +} +``` + +## Pages components + +Then we can use `$store.state.authUser` in our pages components to check if the user is connected in our application or not. + +### Redirect user if not connected + +Let's add a `/secret` route where only the connected user can see its content: +```html +<template> + <div> + <h1>Super secret page</h1> + <router-link to="/">Back to the home page</router-link> + </div> +</template> + +<script> +export default { + // we use fetch() because we do not need to set data to this component + fetch ({ store, redirect }) { + if (!store.state.authUser) { + return redirect('/') + } + } +} +</script> +``` + +We can see in the `fetch` method that we call `redirect('/')` when our user is not connected. diff --git a/es/examples/cached-components.md b/es/examples/cached-components.md new file mode 100644 index 000000000..1f95cb110 --- /dev/null +++ b/es/examples/cached-components.md @@ -0,0 +1,6 @@ +--- +title: Cached Components +description: Cached Components example with Nuxt.js +github: cached-components +documentation: /api/configuration-cache +--- \ No newline at end of file diff --git a/es/examples/custom-loading.md b/es/examples/custom-loading.md new file mode 100644 index 000000000..d2715818b --- /dev/null +++ b/es/examples/custom-loading.md @@ -0,0 +1,7 @@ +--- +title: Custom Loading Component +description: Custom Loading Component example with Nuxt.js +github: custom-loading +livedemo: https://custom-loading.nuxtjs.org +documentation: /api/configuration-loading +--- diff --git a/es/examples/custom-routes.md b/es/examples/custom-routes.md new file mode 100644 index 000000000..a9887d9d1 --- /dev/null +++ b/es/examples/custom-routes.md @@ -0,0 +1,7 @@ +--- +title: Custom Routes +description: Custom Routes example with Nuxt.js +github: custom-routes +livedemo: https://custom-routes.nuxtjs.org +documentation: /guide/routing#dynamic-routes +--- diff --git a/es/examples/global-css.md b/es/examples/global-css.md new file mode 100644 index 000000000..ecf624f44 --- /dev/null +++ b/es/examples/global-css.md @@ -0,0 +1,7 @@ +--- +title: Global CSS +description: Global CSS example with Nuxt.js +github: global-css +livedemo: https://global-css.nuxtjs.org +documentation: /api/configuration-css +--- diff --git a/es/examples/hello-world.md b/es/examples/hello-world.md new file mode 100644 index 000000000..472023d18 --- /dev/null +++ b/es/examples/hello-world.md @@ -0,0 +1,9 @@ +--- +title: Hello World +description: Hello World example with Nuxt.js +github: hello-world +youtube: https://www.youtube.com/embed/kmf-p-pTi40 +livedemo: https://hello-world.nuxtjs.org +liveedit: https://gomix.com/#!/project/nuxt-hello-world +documentation: /guide/installation#starting-from-scratch +--- diff --git a/es/examples/i18n.md b/es/examples/i18n.md new file mode 100644 index 000000000..ab3b9c629 --- /dev/null +++ b/es/examples/i18n.md @@ -0,0 +1,7 @@ +--- +title: Internationalization (i18n) +description: Internationalization (i18n) example with Nuxt.js +github: i18n +livedemo: https://i18n.nuxtjs.org +documentation: /guide/routing#middleware +--- diff --git a/es/examples/layouts.md b/es/examples/layouts.md new file mode 100644 index 000000000..c5960c826 --- /dev/null +++ b/es/examples/layouts.md @@ -0,0 +1,8 @@ +--- +title: Layouts +description: Layouts example with Nuxt.js +github: custom-layouts +livedemo: https://nuxt-custom-layouts.gomix.me/ +liveedit: https://gomix.com/#!/project/nuxt-custom-layouts +documentation: /guide/views#layouts +--- diff --git a/es/examples/menu.json b/es/examples/menu.json new file mode 100644 index 000000000..45980e702 --- /dev/null +++ b/es/examples/menu.json @@ -0,0 +1,33 @@ +[ + { + "title": "Essentials", + "links": [ + { "name": "Hello world", "to": "" }, + { "name": "SEO HTML Head", "to": "/seo-html-head" } + ] + }, + { + "title": "Customization", + "links": [ + { "name": "Cached Components", "to": "/cached-components" }, + { "name": "Custom Loading", "to": "/custom-loading" }, + { "name": "Custom Routes", "to": "/custom-routes" }, + { "name": "Global CSS", "to": "/global-css" }, + { "name": "Layouts", "to": "/layouts" }, + { "name": "Middleware", "to": "/middleware" }, + { "name": "Nested Routes", "to": "/nested-routes" }, + { "name": "Plugins", "to": "/plugins" }, + { "name": "Routes transitions", "to": "/routes-transitions" } + ] + }, + { + "title": "Advanced", + "links": [ + { "name": "Async Data", "to": "/async-data" }, + { "name": "Auth Routes", "to": "/auth-routes" }, + { "name": "Vuex Store", "to": "/vuex-store" }, + { "name": "i18n", "to": "/i18n" }, + { "name": "Testing", "to": "/testing" } + ] + } +] diff --git a/es/examples/middleware.md b/es/examples/middleware.md new file mode 100644 index 000000000..afd8a1552 --- /dev/null +++ b/es/examples/middleware.md @@ -0,0 +1,7 @@ +--- +title: Middleware +description: Middleware example with Nuxt.js +github: middleware +livedemo: https://middleware.nuxtjs.org +documentation: /guide/routing#middleware +--- diff --git a/es/examples/nested-routes.md b/es/examples/nested-routes.md new file mode 100644 index 000000000..471fd28cc --- /dev/null +++ b/es/examples/nested-routes.md @@ -0,0 +1,7 @@ +--- +title: Nested Routes +description: Nested Routes example with Nuxt.js +github: nested-routes +livedemo: https://nested-routes.nuxtjs.org +documentation: /guide/routing#nested-routes +--- diff --git a/es/examples/plugins.md b/es/examples/plugins.md new file mode 100644 index 000000000..d33ed90a5 --- /dev/null +++ b/es/examples/plugins.md @@ -0,0 +1,7 @@ +--- +title: Plugins +description: Using external modules and plugins with nuxt.js +github: plugins-vendor +livedemo: https://plugins-vendor.nuxtjs.org +documentation: /guide/plugins +--- diff --git a/es/examples/routes-transitions.md b/es/examples/routes-transitions.md new file mode 100644 index 000000000..913888b35 --- /dev/null +++ b/es/examples/routes-transitions.md @@ -0,0 +1,8 @@ +--- +title: Routes transitions +description: Routes transitions example with Nuxt.js +github: routes-transitions +youtube: https://www.youtube.com/embed/RIXOzJWFfc8 +livedemo: https://routes-transitions.nuxtjs.org +documentation: /guide/routing#transitions +--- diff --git a/es/examples/seo-html-head.md b/es/examples/seo-html-head.md new file mode 100644 index 000000000..02525b10b --- /dev/null +++ b/es/examples/seo-html-head.md @@ -0,0 +1,7 @@ +--- +title: SEO HTML Head +description: SEO HTML Head example with Nuxt.js +github: head-elements +livedemo: https://head-elements.nuxtjs.org +documentation: /guide/views#html-head +--- diff --git a/es/examples/testing.md b/es/examples/testing.md new file mode 100644 index 000000000..1221672b4 --- /dev/null +++ b/es/examples/testing.md @@ -0,0 +1,6 @@ +--- +title: Testing +description: Testing example with Nuxt.js +github: with-ava +documentation: /guide/development-tools#end-to-end-testing +--- diff --git a/es/examples/vuex-store.md b/es/examples/vuex-store.md new file mode 100644 index 000000000..e4ff096c1 --- /dev/null +++ b/es/examples/vuex-store.md @@ -0,0 +1,7 @@ +--- +title: Vuex Store +description: Vuex Store example with Nuxt.js +github: vuex-store +livedemo: https://vuex-store.nuxtjs.org +documentation: /guide/vuex-store +--- diff --git a/es/faq/async-data-components.md b/es/faq/async-data-components.md new file mode 100644 index 000000000..b96e4e2f2 --- /dev/null +++ b/es/faq/async-data-components.md @@ -0,0 +1,14 @@ +--- +title: Async data in components +description: Async data in components? +--- + +# Async data in components? + +It is not possible because it's not linked to a route, Nuxt.js surcharges the component data() associated to a route to allow async data. + +For sub components, there are 2 ways of achieving it: +1. Making the API call in the mounted() hook and setting the data afterwards, downside: no server rendering +2. Making the API call in the data() of the page component and giving the data as a prop to the subComponent: server rendering OK. But the data() of the page might be less readable because it's loading the async data of the sub components + +It all depends if you want the sub components to be server-rendered or not. diff --git a/es/faq/css-flash.md b/es/faq/css-flash.md new file mode 100644 index 000000000..41a5ed34e --- /dev/null +++ b/es/faq/css-flash.md @@ -0,0 +1,12 @@ +--- +title: CSS Flash +description: Why a CSS Flash appears with Nuxt.js? +--- + +# Why a CSS Flash appears? + +![cssflash](/flash_css.gif) + +This is because the CSS is in the JavaScript build in **development mode** to allow hot-reloading via Webpack. + +Don't worry in production mode, the CSS is separated and put in the header so this "flash" does not appear anymore. diff --git a/es/faq/duplicated-meta-tags.md b/es/faq/duplicated-meta-tags.md new file mode 100644 index 000000000..235a51f11 --- /dev/null +++ b/es/faq/duplicated-meta-tags.md @@ -0,0 +1,42 @@ +--- +title: Duplicated Meta tags +description: Duplicated Meta tags with Nuxt.js? +--- + +# Duplicated Meta tags? + +This is a "feature" of [vue-meta](https://github.com/declandewet/vue-meta), please take a look at the [documentation of head elements](https://nuxtjs.org/guide/html-head#defaults-meta). + +> To avoid any duplication when used in child component, please give a unique identifier with the hid key, please [read more](https://github.com/declandewet/vue-meta#lists-of-tags) about it. + +For the meta description, you need to add the unique identifier `hid` so vue-meta will know that it has to overwrite the default tag. + +Your `nuxt.config.js`: +```js +...head: { + title: 'starter', + meta: [ + { charset: 'utf-8' }, + { name: 'viewport', content: 'width=device-width, initial-scale=1' }, + { name: 'keywords', content: 'keyword 1, keyword 2'}, + { hid: 'description', name: 'description', content: 'This is the generic description.'} + ], + }, +... +``` + +An then in your individual page: +```js +export default { + head () { + return { + title: `Page 1 (${this.name}-side)`, + meta: [ + { hid: 'description', name: 'description', content: "Page 1 description" } + ], + } + } +} +``` + +To learn how to use the `head` property in your pages, please see the [HTML head documentation](/guide/views/#html-head). diff --git a/es/faq/extend-webpack.md b/es/faq/extend-webpack.md new file mode 100644 index 000000000..c2500ad25 --- /dev/null +++ b/es/faq/extend-webpack.md @@ -0,0 +1,18 @@ +--- +title: Extend Webpack +description: How to extend webpack config? +--- + +# How to extend webpack config? + +You can extend the webpack configuration via the `extend` option in your `nuxt.config.js`: + +```js +module.exports = { + build: { + extend (config, { isDev, isClient }) { + // ... + } + } +} +``` diff --git a/es/faq/external-resources.md b/es/faq/external-resources.md new file mode 100644 index 000000000..a12f2a51e --- /dev/null +++ b/es/faq/external-resources.md @@ -0,0 +1,46 @@ +--- +title: External resources +description: How to use external resources with Nuxt.js? +--- + +# How to use external resources? + +## Global Settings + +Include your resources in the `nuxt.config.js` file: + +```js +module.exports = { + head: { + script: [ + { src: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js' } + ], + link: [ + { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css?family=Roboto' } + ] + } +} +``` + +## Local Settings + +Include your resources in your .vue file inside the pages directory: + +```html +<template> + <h1>About page with jQuery and Roboto font</h1> +</template> + +<script> +export default { + head: { + script: [ + { src: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js' } + ], + link: [ + { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css?family=Roboto' } + ] + } +} +</script> +``` diff --git a/es/faq/github-pages.md b/es/faq/github-pages.md new file mode 100644 index 000000000..205dabb37 --- /dev/null +++ b/es/faq/github-pages.md @@ -0,0 +1,44 @@ +--- +title: Github Pages Deployment +description: How to deploy Nuxt.js on Github Pages? +--- + +# How to deploy on Github Pages? + +Nuxt.js gives you the possibility to host your web application on any static hosting like [Github Pages](https://pages.github.com/) for example. + +To deploy on Github Pages, you need to generate your static web application: + +```bash +npm run generate +``` + +It will create a `dist` folder with everything inside ready to be deployed on Github Pages hosting. +Branch `gh-pages` for project repository OR branch `master` for user or organization site + +## Command line deployment + +You can also use [push-dir package](https://github.com/L33T-KR3W/push-dir): + +First install it via npm: +```bash +npm install push-dir --save-dev +``` + +Add a `deploy` command to your package.json with the branch as `gh-pages` for project repository OR `master` for user or organization site. + +```js +"scripts": { + "dev": "nuxt", + "build": "nuxt build", + "start": "nuxt start", + "generate": "nuxt generate", + "deploy": "push-dir --dir=dist --branch=gh-pages --cleanup" +}, +``` + +Then generate and deploy your static application: +```bash +npm run generate +npm run deploy +``` diff --git a/es/faq/google-analytics.md b/es/faq/google-analytics.md new file mode 100644 index 000000000..7987d704e --- /dev/null +++ b/es/faq/google-analytics.md @@ -0,0 +1,60 @@ +--- +title: Google Analytics Integration +description: How to use Google Analytics? +--- + +# How to use Google Analytics? + +To use [Google Analytics](https://analytics.google.com/analytics/web/) with your nuxt.js application, we recommend to create a file `plugins/ga.js`: + +```js +/* +** Only run on client-side and only in production mode +*/ +if (process.BROWSER_BUILD && process.env.NODE_ENV === 'production') { + /* + ** Include Google Analytics Script + */ + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); + /* + ** Set the current page + */ + ga('create', 'UA-XXXXXXXX-X', 'auto') + ga('send', 'pageview') + /* + ** When the app is mounted + */ + window.onNuxtReady((app) => { + /* + ** Every time the route changes + */ + app.$nuxt.$on('routeChanged', (to, from) => { + /* + ** We tell Google Analytic to add a page view + */ + ga('set', 'page', to.fullPath) + ga('send', 'pageview') + }) + }) +} +``` + +> Replace `UA-XXXXXXXX-X` by your Google Analytics tracking ID. + +Then, we tell nuxt.js to import it in our main application: + +`nuxt.config.js` +```js +module.exports = { + plugins: [ + '~plugins/ga.js' + ] +} +``` + +Voilà, Google Analytics is integrated into your nuxt.js application and will track every page view! + +<p class="Alert Alert--nuxt-green"><b>INFO:</b> you can use this method for any other tracking service.</p> diff --git a/es/faq/heroku-deployment.md b/es/faq/heroku-deployment.md new file mode 100644 index 000000000..d077f027f --- /dev/null +++ b/es/faq/heroku-deployment.md @@ -0,0 +1,40 @@ +--- +title: Heroku Deployment +description: How to deploy Nuxt.js on Heroku? +--- + +# How to deploy on Heroku? + +We recommend you to read the [Heroku documentation for node.js](https://devcenter.heroku.com/articles/nodejs-support). + +First, we need to tell Heroku to install the `devDependencies` of the project (to be able to launch `npm run build`): +```bash +heroku config:set NPM_CONFIG_PRODUCTION=false +``` + +Also, we want our application to listen on the port `0.0.0.0` and run in production mode: +```bash +heroku config:set HOST=0.0.0.0 +heroku config:set NODE_ENV=production +``` + +You should see this in your Heroku dashboard (Settings section): + +![nuxt config vars Heroku](https://i.imgur.com/EEKl6aS.png) + +Then, we tell Heroku to launch `npm run build` via the `heroku-postbuild` script in our `package.json`: +```js +"scripts": { + "dev": "nuxt", + "build": "nuxt build", + "start": "nuxt start", + "heroku-postbuild": "npm run build" +} +``` + +Finally, we can push the app on Heroku with: +```bash +git push heroku master +``` + +Voilà! Your nuxt.js application is now hosted on Heroku! diff --git a/es/faq/host-port.md b/es/faq/host-port.md new file mode 100644 index 000000000..bdfcfcbac --- /dev/null +++ b/es/faq/host-port.md @@ -0,0 +1,26 @@ +--- +title: HOST and PORT +description: How to edit HOST and PORT with Nuxt.js? +--- + +# How to edit HOST and PORT? + +You can configure the PORT with 2 different ways: +- Via a env variables +```js +"scripts": { + "dev": "HOST=0.0.0.0 PORT=3333 nuxt" +} +``` +- Via a nuxt config in the `package.json`: +```js +"config": { + "nuxt": { + "host": "0.0.0.0", + "port": "3333" + } +}, +"scripts": { + "dev": "nuxt" +} +``` diff --git a/es/faq/jsx.md b/es/faq/jsx.md new file mode 100644 index 000000000..41b2bd683 --- /dev/null +++ b/es/faq/jsx.md @@ -0,0 +1,27 @@ +--- +title: JSX +description: How to use JSX with Nuxt.js? +--- + +# How to use JSX? + +Nuxt.js use the official [babel-preset-vue-app](https://github.com/vuejs/babel-preset-vue-app) for babel default configuration, so you can use JSX in your components. + +You can now use JSX in your `render` method of your components: + +```html +<script> +export default { + data () { + return { name: 'World' } + }, + render (h) { + return <h1 class="red">{this.name}</h1> + } +} +</script> +``` + +<p class="Alert Alert--info">Aliasing `createElement` to `h` is a common convention you’ll see in the Vue ecosystem and is actually required for JSX. If `h` is not available in the scope, **your app will throw an error**.</p> + +You can learn more how to use it in the [JSX section](https://vuejs.org/v2/guide/render-function.html#JSX) of the Vue.js documentation. diff --git a/es/faq/menu.json b/es/faq/menu.json new file mode 100644 index 000000000..ba43e2a84 --- /dev/null +++ b/es/faq/menu.json @@ -0,0 +1,33 @@ +[ + { + "title": "Configuration", + "links": [ + { "name": "How to use external resources?", "to": "" }, + { "name": "How to use pre-processors?", "to": "/pre-processors" }, + { "name": "How to use JSX?", "to": "/jsx" }, + { "name": "How to add postcss plugins?", "to": "/postcss-plugins" }, + { "name": "How to extend webpack config?", "to": "/extend-webpack" }, + { "name": "How to add webpack plugins?", "to": "/webpack-plugins" }, + { "name": "How to edit HOST and PORT?", "to": "/host-port" }, + { "name": "How to use Google Analytics?", "to": "/google-analytics" } + ] + }, + { + "title": "Development", + "links": [ + { "name": "Window/Document undefined?", "to": "/window-document-undefined" }, + { "name": "Why a CSS Flash appears?", "to": "/css-flash" }, + { "name": "Async data in components?", "to": "/async-data-components" }, + { "name": "Duplicated Meta Tags?", "to": "/duplicated-meta-tags" } + ] + }, + { + "title": "Deployment", + "links": [ + { "name": "How to deploy on Heroku?", "to": "/heroku-deployment" }, + { "name": "How to deploy with Now.sh?", "to": "/now-deployment" }, + { "name": "How to deploy with Surge.sh?", "to": "/surge-deployment" }, + { "name": "How to deploy on Github?", "to": "/github-pages" } + ] + } +] diff --git a/es/faq/now-deployment.md b/es/faq/now-deployment.md new file mode 100644 index 000000000..e796d437d --- /dev/null +++ b/es/faq/now-deployment.md @@ -0,0 +1,25 @@ +--- +title: Now Deployment +description: How to deploy Nuxt.js with Now.sh? +--- + +# How to deploy with Now.sh? + +To deploy with [now.sh](https://zeit.co/now) a `package.json` like follows is recommended: +```json +{ + "name": "my-app", + "dependencies": { + "nuxt": "latest" + }, + "scripts": { + "dev": "nuxt", + "build": "nuxt build", + "start": "nuxt start" + } +} +``` + +Then run `now` and enjoy! + +Note: we recommend putting `.nuxt` in `.npmignore` or `.gitignore`. diff --git a/es/faq/postcss-plugins.md b/es/faq/postcss-plugins.md new file mode 100644 index 000000000..3f83d2476 --- /dev/null +++ b/es/faq/postcss-plugins.md @@ -0,0 +1,20 @@ +--- +title: Postcss plugins +description: How to add postcss plugins? +--- + +# How to add postcss plugins? + +In your `nuxt.config.js` file: + +```js +module.exports = { + build: { + postcss: [ + require('postcss-nested')(), + require('postcss-responsive-type')(), + require('postcss-hexrgba')(), + ] + } +} +``` diff --git a/es/faq/pre-processors.md b/es/faq/pre-processors.md new file mode 100644 index 000000000..235ad9ce3 --- /dev/null +++ b/es/faq/pre-processors.md @@ -0,0 +1,31 @@ +--- +title: Pre-processors +description: How to use pre-processors with Nuxt.js? +--- + +# How to use pre-processors? + +Thanks to [vue-loader](http://vue-loader.vuejs.org/en/configurations/pre-processors.html), you can use any kind of pre-processors for your `<template>`, `<script>` or `<style>`: simply use the `lang` attribute. + +Example of our `pages/index.vue` using [Pug](https://github.com/pugjs/pug), [CoffeeScript](http://coffeescript.org) and [Sass](http://sass-lang.com/): + +```html +<template lang="pug"> + h1.red Hello {{ name }}! +</template> + +<script lang="coffee"> +module.exports = data: -> + { name: 'World' } +</script> + +<style lang="sass"> +.red + color: red +</style> +``` + +To be able to use these pre-processors, we need to install their webpack loaders: +```bash +npm install --save-dev pug@2.0.0-beta6 pug-loader coffee-script coffee-loader node-sass sass-loader +``` diff --git a/es/faq/surge-deployment.md b/es/faq/surge-deployment.md new file mode 100644 index 000000000..7af82dec5 --- /dev/null +++ b/es/faq/surge-deployment.md @@ -0,0 +1,33 @@ +--- +title: Surge Deployment +description: How to deploy Nuxt.js with Surge.sh? +--- + +# How to deploy with Surge.sh? + +Nuxt.js gives you the possibility to host your web application on any static hosting like [surge.sh](https://surge.sh/) for example. + +To deploy on surge.sh, first install it on your computer: +```bash +npm install -g surge +``` + +Then, we tell nuxt.js to generate our web application: + +```bash +npm run generate +``` + +It will create a `dist` folder with everything inside ready to be deployed on a static hosting. + +We can then deploy it to surge.sh: + +```bash +surge dist/ +``` + +Done :) + +If you have a project with [dynamic routes](/guide/routing#dynamic-routes), take a look at the [generate configuration](/api/configuration-generate) to tell nuxt.js how to generate these dynamic routes. + +<div class="Alert">When generating your web application with `nuxt generate`, [the context](/api) given to [data()](/guide/async-data#the-data-method) and [fetch()](/guide/vuex-store#the-fetch-method) will not have `req` and `res`.</div> diff --git a/es/faq/webpack-plugins.md b/es/faq/webpack-plugins.md new file mode 100644 index 000000000..0c874b844 --- /dev/null +++ b/es/faq/webpack-plugins.md @@ -0,0 +1,24 @@ +--- +title: Webpack plugins +description: How to add webpack plugins? +--- + +# How to add webpack plugins? + +In your `nuxt.config.js` file: + +```js +const webpack = require('webpack') + +module.exports = { + build: { + plugins: [ + new webpack.ProvidePlugin({ + '$': 'jquery', + '_': 'lodash' + // ...etc. + }) + ] + } +} +``` diff --git a/es/faq/window-document-undefined.md b/es/faq/window-document-undefined.md new file mode 100644 index 000000000..3a405280c --- /dev/null +++ b/es/faq/window-document-undefined.md @@ -0,0 +1,23 @@ +--- +title: Window or Document undefined +description: Window or Document undefined with Nuxt.js? +--- + +# Window or Document undefined? + +This is due to the server-side rendering. +If you need to specify that you want to import a resource only on the client-side, you need to use the `process.BROWSER_BUILD` variable. + +For example, in your .vue file: +```js +if (process.BROWSER_BUILD) { + require('external_library') +} +``` + +Don't forget to add your library in the [vendor bundle](/api/configuration-build#build-vendor) in your `nuxt.config.js`: +```js + build: { + vendor: ['external_library'] + } +``` diff --git a/es/guide/assets.md b/es/guide/assets.md new file mode 100644 index 000000000..dd3bc8e37 --- /dev/null +++ b/es/guide/assets.md @@ -0,0 +1,98 @@ +--- +title: Recursos (Assets) +description: Nuxt usa por defecto vue-loader, file-loader y url-loader en Webpack para un servicio de recursos(assets) robusto, pero también puedes usar la carpeta "Static" para recursos estáticos. +--- + +> Nuxt usa por defecto vue-loader, file-loader y url-loader en Webpack para un servicio de recursos(assets) robusto, pero también puedes usar la carpeta "Static" para recursos estáticos. + +## Webpacked + +Por defecto, [vue-loader](http://vue-loader.vuejs.org/en/) procesa automáticamente tu estilo y archivos de plantilla con `css-loader` y el compilador de plantillas de Vue. En este proceso de compilación, todos los URL de recursos como `<img src="...">`, `background: url(...)` y `@import` de CSS se resuelven como dependencias de módulo. + +Por ejemplo, tenemos este árbol de archivos: + +```bash +-| assets/ +----| image.png +-| pages/ +----| index.vue +``` + +En mi CSS, si uso `url('~assets/image.png')`, se traducirá como `require('~assets/image.png')`. + +O si en mi `pages/index.vue`, uso: +```html +<template> + <img src="~assets/image.png"> +</template> +``` + +Será compilado como: + +```js +createElement('img', { attrs: { src: require('~assets/image.png') }}) +``` + +Como `.png` no es un archivo Javascript, nuxt.js configura Webpack para usar [file-loader](https://github.com/webpack/file-loader) y [url-loader](https://github.com/webpack/url-loader) para manejarlos por ti. + +Los beneficios son: +- `file-loader` te deja designar a dónde copiar y colocar el archivo del recurso, y cómo nombrarlo usando hashes con versión para una mejor caché. +- `url-loader` te permite condicionalmente convertir a una sola línea un archivo como "base-64 data URL" si son más pequeños que un límite dado. Esto puede reducir un número de solicitudes HTTP para archivos triviales. Si el archivo sobrepasa el límite dado, volverá automáticamente a `file-loader`. + +Actualmente, Nuxt.js la configuración de los "loaders" por defecto es: + +```js +[ + { + test: /\.(png|jpe?g|gif|svg)$/, + loader: 'url-loader', + query: { + limit: 1000, // 1KO + name: 'img/[name].[hash:7].[ext]' + } + }, + { + test: /\.(woff2?|eot|ttf|otf)(\?.*)?$/, + loader: 'url-loader', + query: { + limit: 1000, // 1 KO + name: 'fonts/[name].[hash:7].[ext]' + } + } +] +``` + +Lo que significa que cada archivo por debajo de 1 KO será convertido a una sola línea como 'base-64 data URL'. De lo contrario, la imagen/fuente será copiada en su carpeta correspondiente (dentro del directorio `.nuxt`) con un nombre conteniendo "hashes" con versión para un mejor almacenamiento en caché. + +Cuando lancemos nuestra aplicación con `nuxt`, nuestra plantilla en `pages/index.vue`: + +```html +<template> + <img src="~assets/image.png"> +</template> +``` + +Será generada en: +```html +<img src="/_nuxt/img/image.0c61159.png"> +``` + +Si quieres actualizar estos "loaders" o deshabilitarlos, por favor mira en la [configuración de loaders](/api/configuration-build#loaders). + +## Estático + +Si no quieres usar "Webpacked Assets" del directorio de `assets`, puedes crear y usar el directorio `static` en el directorio raíz de tu proyecto. + +Estos archivos serán automáticamente provistos por Nuxt y accesibles en el URL raíz de tu proyecto. + +Esta opción es útil para archivos como `robots.txt` o `sitemap.xml`. + +Desde tu código puedes entonces referirte a estos archivos con `/` en tus URL: + +```html +<!-- Static image from static directory --> +<img src="/my-image.png"/> + +<!-- Webpacked image from assets directory --> +<img src="/assets/my-image-2.png"/> +``` diff --git a/es/guide/async-data.md b/es/guide/async-data.md new file mode 100644 index 000000000..2aabf4f49 --- /dev/null +++ b/es/guide/async-data.md @@ -0,0 +1,114 @@ +--- +title: Data Asincrónica +description: Nuxt.js sobrecarga el método "data" desde vue.js para permitirte un manejo de operación asíncrona antes de configurar los datos del componente. +--- + +> Nuxt.js *sobrecarga* el método `data` desde vue.js para permitirte un manejo de operación asíncrona antes de configurar los datos del componente. + +## El Método data + +`data` es llamada cada vez antes de cargar el componente (**solo para componentes de páginas**). Puede ser llamada desde el lado del servidor o antes de navegar por la ruta correspondiente. Este método recibe [el contexto](/api#context) como primer argumento, puedes usarlo para obtener algunos datos y devolver los datos del componente. + +<div class="Alert Alert--orange">Tú **NO** tienes acceso a la instancia del componente a traves de `this` dentro de `data` porque es llamado **antes de iniciar** el componente.</div> + +Para hacer el método "data" asíncrono, nuxt.js te ofrece diferentes opciones, elige la que se te haga más familiar: + +1. Devolviendo un `Promise`, nuxt.js esperará que la promesa sea resuelta antes de renderizar el componente. +2. Usando la [propuesta async/await](https://github.com/lukehoban/ecmascript-asyncawait) ([aprende más de esto](https://zeit.co/blog/async-and-await)) +3. Define un "callback" como segundo argumento. Tiene que ser llamado de esta manera: `callback(err, data)` + +### Devolviendo una Promesa +```js +export default { + data ({ params }) { + return axios.get(`https://my-api/posts/${params.id}`) + .then((res) => { + return { title: res.data.title } + }) + } +} +``` + +### Usando async/await +```js +export default { + async data ({ params }) { + let { data } = await axios.get(`https://my-api/posts/${params.id}`) + return { title: data.title } + } +} +``` + +### Usando un "callback" +```js +export default { + data ({ params }, callback) { + axios.get(`https://my-api/posts/${params.id}`) + .then((res) => { + callback(null, { title: res.data.title }) + }) + } +} +``` + +### Devolviendo un Objeto + +Si no necesitas hacer ningún llamado asíncrono, puedes simplemente devolver un objeto: + +```js +export default { + data (context) { + return { foo: 'bar' } + } +} +``` + +### Mostrando la "data" + +Cuando el método "data" está establecido, puedes mostrar los datos dentro de tu plantilla como solías hacerlo: + +```html +<template> + <h1>{{ title }}</h1> +</template> +``` + +## El Contexto + +Para ver la lista de claves disponibles en `context`, revisa la [API de data de Páginas](/api). + +## Manejo de Errores + +Nuxt.js agrega el método `error(parámetros)` en el `context`, puedes llamarlo para mostrar la página de error. `params.statusCode` será también usada para renderizar el código de estado apropiado desde el lado del servidor. + +Ejemplo con un `Promise`: +```js +export default { + data ({ params, error }) { + return axios.get(`https://my-api/posts/${params.id}`) + .then((res) => { + return { title: res.data.title } + }) + .catch((e) => { + error({ statusCode: 404, message: 'Post no encontrado' }) + }) + } +} +``` + +Si estás usando el argumento `callback`, puedes llamarlo directamente con el error, nuxt.js llamará el método `error` por ti: +```js +export default { + data ({ params }, callback) { + axios.get(`https://my-api/posts/${params.id}`) + .then((res) => { + callback(null, { title: res.data.title }) + }) + .catch((e) => { + callback({ statusCode: 404, message: 'Post not found' }) + }) + } +} +``` + +Para modificar la página de error, visita la [sección de layouts en VISTAS](/guide/views#layouts). diff --git a/es/guide/commands.md b/es/guide/commands.md new file mode 100644 index 000000000..82ecef932 --- /dev/null +++ b/es/guide/commands.md @@ -0,0 +1,84 @@ +--- +título: Comandos +descripción: Nuxt.js viene con un conjunto de comandos útiles, ambos con fines en desarrollo y producción. +--- + +> Nuxt.js viene con un conjunto de comandos útiles, ambos con fines en desarrollo y producción. + +## Lista de Comandos + +| Comando | Descripción | +|---------|-------------| +| nuxt | Lanza un servidor de desarrollo [localhost:3000](http://localhost:3000) con "hot-reloading". | +| nuxt build | Construye tu aplicación con webpack y minifica los JS & CSS (para producción). | +| nuxt start | Empieza el servidor en modo producción (Después de correr `nuxt build`). | +| nuxt generate | Construye la aplicación y genera cada ruta como un archivo HTML (usado para hosting estático). | + +Debes poner estos comandos en `package.json`: + +```json +"scripts": { + "dev": "nuxt", + "build": "nuxt build", + "start": "nuxt start", + "generate": "nuxt generate" +} +``` + +Luego, puedes lanzar tus comandos vía `npm run <command>` (ejemplo: `npm run dev`). + +## Entorno de Desarrollo + +Para lanzar Nuxt en modo de desarrollo con "hot reloading": + +```bash +nuxt +// o +npm run dev +``` + +## Implementación en Producción + +Nuxt.js te deja elegir entre 2 modos para desplegar tu aplicación: "Server Rendered" o "Static Generated". + +### Implementación del modo "Server Rendered" + +Para desplegar, en lugar de correr nuxt, quizás quieras construir con anticipación. Por lo tanto, construir e iniciar son comandos separados: + +```bash +nuxt build +nuxt start +``` + +Este archivo `package.json` es el recomendado: +```json +{ + "name": "my-app", + "dependencies": { + "nuxt": "latest" + }, + "scripts": { + "dev": "nuxt", + "build": "nuxt build", + "start": "nuxt start" + } +} +``` + +Nota: recomendamos poner `.nuxt` en `.npmignore` o `.gitignore`. + +### Implementación del modo "Static Generated" + +Nuxt.js te da la posibilidad de alojar tu aplicación web en cualquier hosting estático. + +Para generar nuestra aplicación web en archivos estáticos: + +```bash +npm run generate +``` + +Eso creará una carpeta `dist` con todo lo incluido listo para ser desplegado en un hosting estático. + +Si tienes un proyecto con [rutas dinámicas](/guide/routing#dynamic-routes), visita [generar configuración](/api/configuration-generate) para decirle a nuxt.js cómo generar estas rutas dinámicas. + +<div class="Alert">Cuando estes generando tu aplicación web con `nuxt generate`, [el contexto](/api#context) dado a [data()](/guide/async-data#the-data-method) y [fetch()](/guide/vuex-store#the-fetch-method) no tendrá `req` y`res`.</div> diff --git a/es/guide/configuration.md b/es/guide/configuration.md new file mode 100644 index 000000000..17ac6cd8b --- /dev/null +++ b/es/guide/configuration.md @@ -0,0 +1,84 @@ +--- +title: Configuración +description: La configuración por defecto de Nuxt.js cubre la mayoría de usos. Sin embargo, el archivo nuxt.config.js te deja sobreescribirlo. +--- + +> La configuración por defecto de Nuxt.js cubre la mayoría de usos. Sin embargo, el archivo nuxt.config.js te deja sobreescribirlo. + +### build + +Esta opción te permite añadir módulos dentro del archivo vendor.bundle.js generado para reducir el tamaño del app. Es bastante útil cuando se usa módulos externos. + +[Documentación acerca de la integración de la construcción](/api/configuration-build) + +### cache + +Esta opción habilita los componentes en caché para mejorar el rendimiento de renderizado. + +[Documentación acerca de la integración de cache](/api/configuration-cache) + +### css + +Esta opción te permite definir los archivos/módulos/librerías CSS que quieras establecer como globales (incluido en cada página). + +[Documentación acerca de la integración de css](/api/configuration-css) + +### dev + +Esta opción te permite definir el modo de desarrollo o producción de nuxt.js + +[Documentación acerca de la integración de dev](/api/configuration-dev) + +### env + +Esta opción te permite definir las variables de entorno disponibles para el cliente y servidor. + +[Documentación acerca de la integración de env](/api/configuration-env) + +### generate + +Esta opción te permite definir cada valor de parámetros disponible para cada ruta dinámica en tu aplicación que Nuxt.js transforma en archivos HTML. + +[Documentación acerca de la integración de generate](/api/configuration-generate) + +### head + +Esta opción te permite definir todas las etiquetas "meta" por defecto para tu aplicación. + +[Documentación acerca de la integración de head](/api/configuration-head) + +### loading + +Esta opción te permite personalizar la carga del componente de carga predeterminado con Nuxt.js. + +[Documentación acerca de la integración de loading](/api/configuration-loading) + +### plugins + +Esta opción te permite definir los plugins en Javascript para ser ejecutados antes de instanciar la aplicación vue.js de origen. + +[Documentación acerca de la integración de plugins](/api/configuration-plugins) + +### rootDir + +Esta opción te permite definir el área de trabajo de tu aplicación nuxt.js. + +[Documentación acerca de la integración de rootDir](/api/configuration-rootdir) + +### router + +Esta opción te permite sobreescribir la configuración predeterminada de vue-router en Nuxt.js. + +[Documentación acerca de la integración de router](/api/configuration-router) + +### srcDir + +Esta opción te permite definir el directorio fuente de tu aplicación nuxt.js. + +[Documentación acerca de la integración de srcDir](/api/configuration-srcdir) + +### transition + +Esta opción te permite definir las propiedades por defecto de las transiciones de página. + +[Documentación acerca de la integración de transition](/api/configuration-transition) diff --git a/es/guide/contribution-guide.md b/es/guide/contribution-guide.md new file mode 100644 index 000000000..b98544ebe --- /dev/null +++ b/es/guide/contribution-guide.md @@ -0,0 +1,19 @@ +--- +title: Guía de Contribución +description: Cualquier contribución a Nuxt.js es más que bienvenida! +--- + +> Cualquier contribución a Nuxt.js es más que bienvenida! + +## Reportando Problemas + +Una buena manera de contribuir con el proyecto es enviar un reporte detallado cuando encuentres un problema. Siempre apreciamos un reporte de error bien escrito, y te agradeceremos por eso! Antes de reportar un problema, por favor lee cuidadosamente la documentación y busca si algún tema para el problema que tienes ya existe: https://github.com/nuxt/nuxt.js/issues + +## Pull Requests + +Nos encataría ver tus "pull requests", aun así sean para arreglar la tipografía. Cualquier mejora significativa debe ser documentada como [un problema de GitHub](https://github.com/nuxt/nuxt.js/issues) antes de que alguien empiece a trabajar en eso. + +### Convención + +- Para un arreglo, el nombre de la rama (branch) debe ser `fix-XXX` donde XXX es el número de problema o el nombre de lo que arregla +- Para una característica, el nombre de la rama (branch) debe ser `feature-XXX` donde XXX es el número del problema asociado a esta solicitud de característica diff --git a/es/guide/development-tools.md b/es/guide/development-tools.md new file mode 100644 index 000000000..09cd3b25e --- /dev/null +++ b/es/guide/development-tools.md @@ -0,0 +1,164 @@ +--- +title: Herramientas de Desarrollo +description: Nuxt.js hace tu desarrollo web más agradable. +--- + +> Probar tu aplicación es parte del desarrollo web. Nuxt.js te ayuda a hacerlo lo más fácil posible. + +## Pruebas End-to-End + +[Ava](https://github.com/avajs/ava) es un poderoso framework de prueba en JavaScript, combinado con [jsdom](https://github.com/tmpvar/jsdom), podemos usarlos para hacer pruebas end-to-end fácilmente. + +Primero, necesitamos agregar 'ava' y 'jsdom' como dependencias de desarrollo: +```bash +npm install --save-dev ava jsdom +``` + +Y agregamos un "script" "test" a nuestro `package.json` y configuramos ava para compilar archivos que importamos en nuestros tests: + +```javascript +"scripts": { + "test": "ava", + "ava": { + "require": [ + "babel-register" + ] + }, + "babel": { + "presets": [ + "es2015" + ] + } +} +``` + +Vamos a escribir nuestras pruebas en la carpeta `test`: +```bash +mkdir test +``` + +Digamos que tenemos una página en `pages/index.vue`: +```html +<template> + <h1 class="red">Hola {{ name }}!</h1> +</template> + +<script> +export default { + data () { + return { name: 'mundo' } + } +} +</script> + +<style> +.red { + color: red; +} +</style> +``` + +Cuando lanzamos nuestra aplicación con `npm run dev` y abrimos [http://localhost:3000](http://localhost:3000), podemos ver nuestro título rojo `Hola mundo!`. + +Agregamos nuestro archivo de prueba `test/index.test.js`: + +```js +import test from 'ava' +import Nuxt from 'nuxt' +import { resolve } from 'path' + +// Mantenemos la instancia de nuxt y del servidor +// Entonces podemos cerrarlos al final de la prueba +let nuxt = null +let server = null + +// Inicia Nuxt.js y crea un servidor escuchando en localhost:4000 +test.before('Init Nuxt.js', async t => { + const rootDir = resolve(__dirname, '..') + let config = {} + try { config = require(resolve(rootDir, 'nuxt.config.js')) } catch (e) {} + config.rootDir = rootDir // carpeta del proyecto + config.dev = false // "build" de producción + nuxt = new Nuxt(config) + await nuxt.build() + server = new nuxt.Server(nuxt) + server.listen(4000, 'localhost') +}) + +// Ejemplo de prueba generando solo html +test('Route / exits and render HTML', async t => { + let context = {} + const { html } = await nuxt.renderRoute('/', context) + t.true(html.includes('<h1 class="red">Hello world!</h1>')) +}) + +// Ejemplo de prueba vía "dom checking" +test('Route / exits and render HTML with CSS applied', async t => { + const window = await nuxt.renderAndGetWindow('http://localhost:4000/') + const element = window.document.querySelector('.red') + t.not(element, null) + t.is(element.textContent, 'Hello world!') + t.is(element.className, 'red') + t.is(window.getComputedStyle(element).color, 'red') +}) + +// Cierra el servidor y pide a nuxt que deje de escuchar los cambios en los archivos +test.after('Closing server and nuxt.js', t => { + server.close() + nuxt.close() +}) +``` + +Ahora podemos lanzar nuestras pruebas: +```bash +npm test +``` + +"jsdom" tiene algunas limitaciones porque no usa un navegador. Sin embargo, cubrirá gran parte de nuestras pruebas. Si quieres usar un navegador para probar tu aplicación, quizás quieres revisar [Nightwatch.js](http://nightwatchjs.org). + +## ESLint + +> ESLint es una gran herramienta para mantener tu código limpio + +Puedes agregar [ESLint](http://eslint.org) bastante fácil con nuxt.js, primero, necesitas agregar las dependencias npm: + +```bash +npm install --save-dev babel-eslint eslint eslint-config-standard eslint-plugin-html eslint-plugin-promise eslint-plugin-standard +``` + +Luego, puedes configurar ESLint vía un archivo `.eslintrc.js` en el directorio origen de tu proyecto: +```js +module.exports = { + root: true, + parser: 'babel-eslint', + env: { + browser: true, + node: true + }, + extends: 'standard', + // requerido para "lint" los archivos *.vue + plugins: [ + 'html' + ], + // agrega tus reglas personalizadas aquí + rules: {}, + globals: {} +} +``` + +Después, puedes agregar un script `lint` en tu `package.json`: + +```js +"scripts": { + "lint": "eslint --ext .js,.vue --ignore-path .gitignore ." +} +``` + +Ahora puedes lanzar: +```bash +npm run lint +``` + +ESLint revisará(lint) cada archivo en JavaScript y Vue mientras ignora tus archivos ignorados definidos en `.gitignore`. + +<p class="Alert Alert--info">Lo mejor que puedes hacer es también agregar `"precommit": "npm run lint"` en tu package.json para revisar (lint) tu código automáticamente antes de confirmarlo (commit).</p> diff --git a/es/guide/directory-structure.md b/es/guide/directory-structure.md new file mode 100644 index 000000000..2c29a0f36 --- /dev/null +++ b/es/guide/directory-structure.md @@ -0,0 +1,94 @@ +--- +title: Estructura del Directorio +description: La estructura predeterminada de una aplicación Nuxt.js tiene el propósito de proveer un gran punto de partida para aplicaciones grandes y pequeñas. +--- + +> La estructura predeterminada de una aplicación Nuxt.js tiene el propósito de proveer un gran punto de partida para aplicaciones grandes y pequeñas. Por supuesto, tú eres libre de organizar tu aplicación como te guste. + +## Directorios + +### Directorio de Recursos (Assets) + +El directorio de `assets` contiene tus 'assets' sin compilar como LESS, SASS o JavaScript. + +[Más documentación acerca de la integración de Assets](/guide/assets) + +### El Directorio de los Componentes + +El directorio llamado `components` contiene tus componentes de Vue.js. Nuxt.js no recarga el método de datos en estos componentes. + +### El Directorio de Layouts + +El directorio llamado `layouts` contiene los "Layouts" de tu Aplicación. + +_Este directorio no puede ser renombrado._ + +[Más documentación acerca de la integración de Layouts](/guide/views#layouts) + +### El Directorio Middleware + +_Pronto_ + +### El Directorio de Páginas + +El directorio llamado `pages` contiene las Vistas y Rutas de tu Aplicación. El framework lee todos los archivos `.vue` dentro de este directorio y crea el enrutador de tu aplicación. + +_Este directorio no puede ser renombrado._ + +[Más documentación acerca de la integración de Páginas](/guide/views) + +### El Directorio de Plugins + +El directorio llamado `plugins` contiene los plugins en Javascript que quieres ejecutar antes de instanciar la aplicación vue.js de origen. + +[Más documentación acerca de la integración de Plugins](/guide/plugins) + +### El Directorio "Static" + +El directorio de `static` contiene tus archivos estáticos. Cada archivo dentro de este directorio está mapeado a /. + +**Ejemplo:** /static/robots.txt está mapeado como /robots.txt + +_Este directorio no puede ser renombrado._ + +[Más documentación acerca de la integración de Static](/guide/assets#static) + +### El Directorio "Store" + +El directorio llamado `store` contiene tus archivos [Vuex Store](http://vuex.vuejs.org). La opción de Vuex Store es implementada en el framework de Nuxt.js. Creando un archivo `index.js` en este directorio activa automáticamente la opción en el framework. + +_Este directorio no puede ser renombrado._ + +[Más documentación acerca de la integración de Store](/guide/vuex-store) + +### El Archivo nuxt.config.js + +El archivo `nuxt.config.js` contiene tu configuración personalizada de Nuxt.js. + +_Este archivo no puede ser renombrado._ + +[Más documentación acerca de la integración de nuxt.config.js](/guide/configuration) + +### El Archivo package.json + +El archivo `package.json` contiene las dependencias y "scripts" de tu Aplicación. + +_Este archivo no puede ser renombrado._ + +## Alias + +| Alias | Directorio | +|-----|------| +| ~ | / | +| ~assets | /assets | +| ~components | /components | +| ~pages | /pages | +| ~plugins | /plugins | +| ~static | /static | + +Alias que enlazan a archivos: + +| Alias | Uso | Descripción | +|-------|------|--------------| +| ~store | `const store = require('~store')` | Import the `vuex` store instance. | +| ~router | `const router = require('~router')`| Import the `vue-router` instance. | diff --git a/es/guide/index.md b/es/guide/index.md new file mode 100644 index 000000000..363a65a27 --- /dev/null +++ b/es/guide/index.md @@ -0,0 +1,102 @@ +--- +title: Introducción +description: "El 25 de Octubre de 2016, el equipo detrás de zeit.co, anunció Next.js, un framework para aplicaciónes server-rendered con React. Pocas horas después del anuncio, la idea de crear aplicaciónes server-rendered con Vue.js de la misma forma que Next.js era obvia: Nuxt.js nació." +--- + +> El 25 de Octubre de 2016, el equipo detrás de [zeit.co](https://zeit.co/), anunció [Next.js](https://zeit.co/blog/next),un framework para aplicaciónes server-rendered con React. Pocas horas después del anuncio, la idea de crear aplicaciónes server-rendered con [Vue.js](https://vuejs.org) de la misma forma que Next.js era obvia: **Nuxt.js** nació. + +## ¿ Qué es Nuxt.js ? + +Nuxt.js es un framework para crear Aplicaciones Universales con Vue.js + +Su ámbito principal es **UI rendering** al abstraer la distribución cliente/servidor. + +Nuestra meta es crear un framework lo suficientemente flexible para que lo puedas usar como la base principal de un proyecto o en tu actual proyecto basado en Node.js. + +Nuxt.js preasigna toda la configuración que se necesita para hacer que tu Aplicación con Vue.js **Server Rendered** sea más agradable. + +Además, tenemos otra opción de despliegue llamada: *nuxt generate*. Esta construirá una Aplicación **Static Generated** con Vue.js. +Creemos que esta opción puede ser el próximo gran paso en el desarrollo de Aplicaciones Web con microservicios. + +Como un framework, Nuxt.js viene con varias características para ayudarte en tu desarrollo entre el lado del cliente y el lado del servidor como Data Asíncrona, Middleware, Layouts, etc. + +## ¿ Cómo Funciona ? + +![Vue con Webpack y Babel](https://i.imgur.com/avEUftE.png) + +Nuxt.js incluye lo siguiente para crear un desarrollo de aplicaciones web robusto: +- [Vue 2](https://github.com/vuejs/vue) +- [Vue-Router](https://github.com/vuejs/vue-router) +- [Vuex](https://github.com/vuejs/vuex) (incluido solo cuando se usa [store option](/guide/vuex-store)) +- [Vue-Meta](https://github.com/declandewet/vue-meta) + +Un total de solo **28kb min+gzip** (31kb con vuex). + +Bajo el capó usamos [Webpack](https://github.com/webpack/webpack) con [vue-Loader](https://github.com/vuejs/vue-loader) y [babel-loader](https://github.com/babel/babel-loader) para agrupar, code-split y minimizar tu código. + +## Características + +- Escribe Archivos Vue +- División automática de Código +- Server-Side Rendering +- Powerful Routing System with Asynchronous Data +- Servir Archivos Estáticos +- Transpilación ES6/ES7 +- Agrupación y minimización de tu JS & CSS +- Gestionar Elementos Head +- Hot reloading en Desarrollo +- Pre-procesadores: SASS, LESS, Stylus, etc + +## Esquema + +Este esquema muestra lo que es llamado por nuxt.js cuando el servidor es llamado o cuando el usuario navega a través de la aplicación via `<nuxt-link>`: + +![nuxt-schema](/nuxt-schema.png) + +## Renderizado desde el Servidor (Server Rendered) + +Puedes usar nuxt.js como un framework para gestionar todo el renderizado de la interfase de usuario de tu proyecto. + +Cuando inicias `nuxt`, este empezará un servidor de d"esarrollo con "hot-reloading" y "vue-server-renderer configurado para automáticamente "server-render" tu aplicación. + +Dale una revisada a [los comandos](/guide/commands) para aprender más acerca de esto. + +Si ya tienes un servidor, puedes conectar nuxt.js usandolo como un "middleware", no hay restricciones en lo absoluto cuando usas nuxt.js para desarrollar tu Aplicación Web Universal, mira la guía [Usando Nuxt.js Programáticamente](/api/nuxt). + +## Generado Estáticamente (Static Generated) + +La gran innovación de nuxt.js viene aquí: `nuxt generate` + +Cuando construyas tu aplicación se generará el HTML de cada una de tus rutas para guardarlas en un archivo. + +Ejemplo: + +```bash +-| pages/ +----| about.vue +----| index.vue +``` + +Generará: +``` +-| dist/ +----| about/ +------| index.html +----| index.html +``` + +De este modo, puedes hospedar tu aplicación web generada en cualquier "static hosting"! + +El mejor ejemplo es esta página. Esta generada y hospedad en "Github Pages": +- [Código fuente](https://github.com/nuxt/nuxtjs.org) +- [Código generado](https://github.com/nuxt/nuxtjs.org/tree/gh-pages) + +No queremos generar manualmente la aplicación cada vez que actualizamos los [repositorios de la documentación](https://github.com/nuxt/docs), así que en pada "push" llamamos a una función AWS Lambda con: +1. Clonar el [repositorio nuxtjs.org](https://github.com/nuxt/nuxtjs.org) +2. Instalar las dependencias via `npm install` +3. Correr `nuxt generate` +4. "Push" la carpeta `dist` al branch `gh-pages` + +Ahora tenemos una **Aplicación Web Estáticamente Generada sin Servidor** (Serverless Static Generated Web Application) :) + +Podemos ir más lejos si pensamos en una aplicación web de e-commerce hecha con `nuxt generate` y hospedada en un CDN, y cada vez que un producto se agota o vuelve a estar disponible, regeneramos la aplicación web. Pero si el usuario navega a través de una aplicación web mientras tanto, estará actualizado gracias a las llamadas al API hechas al API del e-commerce. No se necesita tener múltiples instacias de un servidor + un caché nunca más! diff --git a/es/guide/installation.md b/es/guide/installation.md new file mode 100644 index 000000000..5f2077391 --- /dev/null +++ b/es/guide/installation.md @@ -0,0 +1,92 @@ +--- +title: Instalación +description: Es realmente fácil de empezar con Nuxt.js. Un proyecto simple solo necesita la dependencia `nuxt`. +--- + +> Es realmente fácil de empezar con Nuxt.js. Un proyecto simple solo necesita la dependencia `nuxt`. + +## Usando la plantilla de inicio de Nuxt.js + +Para empezar rápidamente, el equipo de the Nuxt.js ha creado una [plantilla de inicio](https://github.com/nuxt/starter). + +[Descarga el .zip](https://github.com/nuxt/starter/archive/source.zip) plantilla de inicio o instálala con vue-cli: + +```bash +$ vue init nuxt/starter <project-name> +``` + +> Si [vue-cli](https://github.com/vuejs/vue-cli) no está instalado, por favor instálalo con `npm install -g vue-cli` + +luego instala las dependencias: + +```bash +$ cd <project-name> +$ npm install +``` + +y lanza el proyecto con: +```bash +$ npm run dev +``` +La aplicación ahora está corriendo en http://localhost:3000 + +<p class="Alert">Nuxt.js escuchará los cambios en los archivos dentro del directorio de `pages`, así que no tendrás que reiniciar la aplicación cuando añadas nuevas páginas</p> + +Para descubrir más acerca de la estructura del directorio del proyecto: [Documentación de la estructura del directorio](/guide/directory-structure). + +## Empezando de cero + +Crear una aplicación con Nuxt.js desde cero es también bastante sencillo, solo necesita *1 archivo y 1 directorio*. Vamos a crear un directorio vacío para empezar a trabajar en la aplicación: + +```bash +$ mkdir <project-name> +$ cd <project-name> +``` + +*Información: reemplaza project-name con el nombre de tu proyecto.* + +### Archivo package.json + +El proyecto necesita un archivo `package.json` para especificar cómo empezar con `nuxt`: +```json +{ + "name": "my-app", + "scripts": { + "dev": "nuxt" + } +} +``` +`scripts` lanzará Nuxt.js vía `npm run dev`. + +### Instalando `nuxt` + +Una vez que `package.json` ha sido creado, agrega `nuxt` al proyecto vía NPM: +```bash +npm install --save nuxt +``` + +### El directorio `pages` + +Nuxt.js transformará cada arhcivo `*.vue` dentro del directorio de `pages` como una ruta para la aplicación. + +Crea el directorio `pages`: +```bash +$ mkdir pages +``` + +luego crea la primera página en `pages/index.vue`: +```html +<template> + <h1>Hello world!</h1> +</template> +``` + +y lanza el proyecto con: +```bash +$ npm run dev +``` +La aplicación está ahora corriendo en http://localhost:3000 + +<p class="Alert">Nuxt.js escuchará los cambios en los archivos dentro del directorio de `pages`, así que no tendrás que reiniciar la aplicación cuando añadas nuevas páginas</p> + +Para descubrir más acerca de la estructura del directorio del proyecto: [Documentación de la estructura del directorio] (/guide/directory-structure). diff --git a/es/guide/menu.json b/es/guide/menu.json new file mode 100644 index 000000000..768bfc761 --- /dev/null +++ b/es/guide/menu.json @@ -0,0 +1,108 @@ +[ + { + "title": "Prólogo", + "links": [ + { + "to": "", "name": "Introducción", + "contents": [ + { "to": "#what-is-nuxt-js-", "name": "¿Qué es Nuxt.js?" }, + { "to": "#how-it-works", "name": "Cómo funciona" }, + { "to": "#features", "name": "Características" }, + { "to": "#schema", "name": "Esquema" }, + { "to": "#server-rendered", "name": "Server Rendered" }, + { "to": "#static-generated", "name": "Static Generated" } + ] + }, + { "to": "/contribution-guide", "name": "Contribution Guide" }, + { "to": "/release-notes", "name": "Release Notes" } + ] + }, + { + "title": "Empezar", + "links": [ + { + "to": "/installation", "name": "Instalación", + "contents": [ + { "to": "#using-nuxt-js-starter-template", "name": "Usando la plantilla de inicio de Nuxt.js" }, + { "to": "#starting-from-scratch", "name": "Empezando desde cero" } + ] + }, + { + "to": "/directory-structure", "name": "Estructura del directorio", + "contents": [ + { "to": "#directories", "name": "Directorios" }, + { "to": "#aliases", "name": "Alias" } + ] + }, + { "to": "/configuration", "name": "Configuración" }, + { + "to": "/routing", "name": "Enrutamiento", + "contents": [ + { "to": "#basic-routes", "name": "Rutas Básicas" }, + { "to": "#dynamic-routes", "name": "Rutas Dinámicas" }, + { "to": "#nested-routes", "name": "Rutas Anidadas" }, + { "to": "#dynamic-nested-routes", "name": "Rutas dinamicamente anidadas" }, + { "to": "#transitions", "name": "Transiciones" }, + { "to": "#middleware", "name": "Middleware" } + ] + }, + { + "to": "/views", "name": "Vistas", + "contents": [ + { "to": "#pages", "name": "Páginas" }, + { "to": "#layouts", "name": "Layouts" }, + { "to": "#html-head", "name": "HTML Head" }, + { "to": "#document", "name": "Document" } + ] + }, + { + "to": "/async-data", "name": "Async Data", + "contents": [ + { "to": "#the-data-method", "name": "El Método data" }, + { "to": "#the-context", "name": "El Contexto (context)" }, + { "to": "#handling-errors", "name": "Manejando Errores" } + ] + }, + { + "to": "/assets", "name": "Assets", + "contents": [ + { "to": "#webpacked", "name": "Webpacked" }, + { "to": "#static", "name": "Estáticos" } + ] + }, + { + "to": "/plugins", "name": "Plugins", + "contents": [ + { "to": "#external-packages", "name": "External Packages" }, + { "to": "#vue-plugins", "name": "Vue Plugins" }, + { "to": "#client-side-only", "name": "Solo desde el cliente (Client-side)" } + ] + }, + { + "to": "/vuex-store", "name": "Vuex Store", + "contents": [ + { "to": "#activate-the-store", "name": "Activate the Store" }, + { "to": "#classic-mode", "name": "Classic mode" }, + { "to": "#modules-mode", "name": "Modules mode" }, + { "to": "#the-fetch-method", "name": "The fetch Method" }, + { "to": "#the-nuxtserverinit-action", "name": "The nuxtServerInit Action" } + ] + }, + { + "to": "/commands", "name": "Comandos", + "contents": [ + { "to": "#list-of-commands", "name": "Lista de Comandos" }, + { "to": "#development-environment", "name": "Developemnt Enviroment" }, + { "to": "#production-deployment", "name": "Production Deployment" } + ] + }, + { + "to": "/development-tools", "name": "Herramientas de desarrollo", + "contents": [ + { "to": "#end-to-end-testing", "name": "End-to-End Testing" }, + { "to": "#eslint", "name": "ESLint" } + ] + } + ] + } +] diff --git a/es/guide/plugins.md b/es/guide/plugins.md new file mode 100644 index 000000000..76c04c1da --- /dev/null +++ b/es/guide/plugins.md @@ -0,0 +1,98 @@ +--- +title: Plugins +description: Nuxt.js te permite definir los plugins js que serán ejecutados antes de instanciar la aplicación vue.js de origen, puede ser para usar tu propia librería o módulos externos. +--- + +> Nuxt.js te permite definir los 'plugins js' que serán ejecutados antes de instanciar la aplicación vue.js de origen, puede ser para usar tu propia librería o módulos externos. + +<div class="Alert">Es importante saber que en cualquier Vue [Ciclo de vida de la instancia](https://vuejs.org/v2/guide/instance.html#Lifecycle-Diagram), solo los "hooks" `beforeCreate` y `created` son llamados **desde el lado del cliente y del servidor**. Todos los otros 'hooks' son llamados solo del lado del cliente.</div> + +## Paquetes Externos + +Es probable que queramos usar paquetes/módulos externos en nuestra aplicación, un gran ejemplo es [axios](https://github.com/mzabriskie/axios) para hacer solicitudes HTTP para el cliente y servidor. + +Lo instalamos vía NPM: + +```bash +npm install --save axios +``` + +Luego, lo podemos usar directamente en nuestra páginas: + +```html +<template> + <h1>{{ title }}</h1> +</template> + +<script> +import axios from 'axios' + +export default { + async data ({ params }) { + let { data } = await axios.get(`https://my-api/posts/${params.id}`) + return { title: data.title } + } +} +</script> +``` + +Pero hay **un problema acá**, si importamos 'axios' en otra página, será incluido de nuevo para el conjunto (bundle) de páginas. Queremos incluir `axios` solo una vez en nuestra aplicación, para esto, usamos la clave `build.vendor` en nuestro `nuxt.config.js`: + +```js +module.exports = { + build: { + vendor: ['axios'] + } +} +``` + +Luego, puedo importar `axios` donde sea sin tener que preocuparme por hacer un conjunto (bundle) más grande! + +## Plugins Vue + +Si queremos usar [vue-notifications](https://github.com/se-panfilov/vue-notifications) para mostrar notificaciones en nuestra aplicación, tenemos que preparar el plugin antes de lanzar el app. + +Archivo `plugins/vue-notifications.js`: +```js +import Vue from 'vue' +import VueNotifications from 'vue-notifications' + +Vue.use(VueNotifications) +``` + +Luego, agregamos el archivo dentro de la clave `plugins` en `nuxt.config.js`: +```js +module.exports = { + plugins: ['~plugins/vue-notifications'] +} +``` + +Para aprender más acerca de la clave de configuración 'plugins', revisa [plugins api](/api/configuration-plugins). + +En realidad, `vue-notifications` será incluido en el paquete del app, pero como es una librería, queremos incluirlo en el paquete de proveedores para tener un mejor caché. + +Podemos actualizar nuestro `nuxt.config.js` tpara agregar `vue-notifications` en el paquete de proveedores: +```js +module.exports = { + build: { + vendor: ['vue-notifications'] + }, + plugins: ['~plugins/vue-notifications'] +} +``` + +## Solo el Lado del Cliente + +Algunos plugins pueden funcionar **solo para el navegador**, puedes usar la variable `process.BROWSER_BUILD` para ver si el plugin se ejecutará desde el lado del cliente. + +Ejemplo: +```js +import Vue from 'vue' +import VueNotifications from 'vue-notifications' + +if (process.BROWSER_BUILD) { + Vue.use(VueNotifications) +} +``` + +En caso necesites algunas librerías solo para el servidor, puedes usar la variable `process.SERVER_BUILD` con valor `true` cuando "webpack" este creando el archivo `server.bundle.js`. diff --git a/es/guide/routing.md b/es/guide/routing.md new file mode 100644 index 000000000..3b5dae5bb --- /dev/null +++ b/es/guide/routing.md @@ -0,0 +1,311 @@ +--- +title: Routing +description: Nuxt.js usa el sistema de archivos para generar las rutas de tus aplicaciones web, es tan simple como PHP para crear rutas. +--- + +> Nuxt.js genera automáticamente la configuración [vue-router](https://github.com/vuejs/vue-router) de acuerdo al árbol de archivos Vue dentro del directorio `pages`. + +## Rutas básicas + +Este árbol de archivos: + +```bash +pages/ +--| user/ +-----| index.vue +-----| one.vue +--| index.vue +``` + +automáticamente generará: + +```js +router: { + routes: [ + { + name: 'index', + path: '/', + component: 'pages/index.vue' + }, + { + name: 'user', + path: '/user', + component: 'pages/user/index.vue' + }, + { + name: 'user-one', + path: '/user/one', + component: 'pages/user/one.vue' + } + ] +} +``` + +## Rutas dinámicas + +Para definir una ruta dinámica con un parámetro, necesitas definir un archivo .vue o un directorio **prefijado por un guión bajo**. + +Este árbol de archivos: + +```bash +pages/ +--| _slug/ +-----| comments.vue +-----| index.vue +--| users/ +-----| _id.vue +--| index.vue +``` + +automáticamente generará: + +```js +router: { + routes: [ + { + name: 'index', + path: '/', + component: 'pages/index.vue' + }, + { + name: 'users-id', + path: '/users/:id?', + component: 'pages/users/_id.vue' + }, + { + name: 'slug', + path: '/:slug', + component: 'pages/_slug/index.vue' + }, + { + name: 'slug-comments', + path: '/:slug/comments', + component: 'pages/_slug/comments.vue' + } + ] +} +``` + +Como puedes ver la ruta con nombre `users-id` tiene el "path" `:id?` lo cual lo hace opcional, si quieres hacerlo necesario, crea un archivo `index.vue` en el directorio `users/_id`. + +### Validar los Parámetros de Ruta + +Nuxt.js te permite definir un método validador dentro de tu componente de ruta dinámica. + +En este ejemplo: `pages/users/_id.vue` + +```js +export default { + validate ({ params }) { + // Debe ser un número + return /^\d+$/.test(params.id) + } +} +``` + +Si el método de validación no regresa `true`, Nuxt.js cargará automáticamente la página de error 404. + +Más información acerca del método de validación: [API de validación de Páginas](/api/pages-validate) + +## Rutas anidadas + +Nuxt.js te permite crear rutas anidadas usando las rutas hijas de vue-router. + +Para definir una ruta anidada, necesitas crear un archivo Vue con el **mismo nombre del directorio** que contiene tus vistas hijas. + +<p class="Alert Alert--info">No olvides escribir `<nuxt-child/>` dentro del componente padre (.vue file).</p> + +Este árbol de archivos: + +```bash +pages/ +--| users/ +-----| _id.vue +-----| index.vue +--| users.vue +``` + +automáticamente generará: + +```js +router: { + routes: [ + { + path: '/users', + component: 'pages/users.vue', + children: [ + { + path: '', + component: 'pages/users/index.vue', + name: 'users' + }, + { + path: ':id', + component: 'pages/users/_id.vue', + name: 'users-id' + } + ] + } + ] +} +``` + +## Rutas Dinámicas Anidadas + +Este escenario no es añadido frecuentemente, pero es posible con Nuxt.js: tener hijos dinámicos dentro de padres dinámicos. + +Este árbol de archivos: + +```bash +pages/ +--| _category/ +-----| _subCategory/ +--------| _id.vue +--------| index.vue +-----| _subCategory.vue +-----| index.vue +--| _category.vue +--| index.vue +``` + +automáticamente generará: + +```js +router: { + routes: [ + { + path: '/', + component: 'pages/index.vue', + name: 'index' + }, + { + path: '/:category', + component: 'pages/_category.vue', + children: [ + { + path: '', + component: 'pages/_category/index.vue', + name: 'category' + }, + { + path: ':subCategory', + component: 'pages/_category/_subCategory.vue', + children: [ + { + path: '', + component: 'pages/_category/_subCategory/index.vue', + name: 'category-subCategory' + }, + { + path: ':id', + component: 'pages/_category/_subCategory/_id.vue', + name: 'category-subCategory-id' + } + ] + } + ] + } + ] +} +``` + +## Transiciones + +Nuxt.js usa el componente [<transition>](http://vuejs.org/v2/guide/transitions.html#Transitioning-Single-Elements-Components) para permitirte crear transiciones/animaciones entre tus rutas. + +### Ajustes Globales + +<p class="Alert Alert--info">El nombre de la transición por defecto de Nuxt.js es `"page"`.</p> + +Para agregar una transición de desvanecimiento a cada página de tu aplicación, necesitamos un archivo CSS que sea compartido a través de todas tus rutas, así que empezamos creando un archivo en la capeta `assets`. + +Nuestro css global en `assets/main.css`: +```css +.page-enter-active, .page-leave-active { + transition: opacity .5s; +} +.page-enter, .page-leave-active { + opacity: 0; +} +``` + +Agregamos su trayectoria en nuestro archivo `nuxt.config.js`: +```js +module.exports = { + css: [ + 'assets/main.css' + ] +} +``` + +Más información acerca de la clave de transición : [API Configuration transition](/api/pages-transition) + +### Ajustes de Página + +También puedes definir una transición personalizada para una sola página con la propiedad `transition`. + +Agregamos una nueva clase en nuestro css global en `assets/main.css`: +```css +.test-enter-active, .test-leave-active { + transition: opacity .5s; +} +.test-enter, .test-leave-active { + opacity: 0; +} +``` + +luego, usamos la propiedad de transición para definir el nombre de la clase que usaremos en está trasición de página: +```js +export default { + transition: 'test' +} +``` + +Más información acerca de la propiedad de transición: [API Pages transition](/api/pages-transition) + +## Middleware + +> El middleware te permite definir una función personalizada que será ejecutada antes de renderizar la página o un grupo de páginas. + +**Cada middleware debe ser puesto en el directorio `middleware/`.** El nombre de archivo será el nombre de middleware (`middleware/auth.js` será el middleware `auth`). + +Un middleware recibe [el contexto](/api#the-context) como primer argumento: + +```js +export default function (context) { + context.userAgent = context.isServer ? context.req.headers['user-agent'] : navigator.userAgent +} +``` + +El middleware será ejecutado en series en este orden: +1. `nuxt.config.js` +2. Matched layouts +3. Matched pages + +Un middleware puede ser asíncrono, simplemente regresa un `Promise` o usa el segundo argumento `callback`: + +`middleware/stats.js` +```js +import axios from 'axios' + +export default function ({ route }) { + return axios.post('http://my-stats-api.com', { + url: route.fullPath + }) +} +``` + +Luego, en tu `nuxt.config.js`, "layout" o página, usa la clave `middleware`: + +`nuxt.config.js` +```js +module.exports = { + router: { + middleware: 'stats' + } +} +``` + +El middleware `stats` será llamado en cada cambio de ruta. + +Para ver un ejemplo de la vida real usando middleware, por favor revisa [example-auth0](https://github.com/nuxt/example-auth0) en GitHub. diff --git a/es/guide/views.md b/es/guide/views.md new file mode 100644 index 000000000..a05db5a1d --- /dev/null +++ b/es/guide/views.md @@ -0,0 +1,201 @@ +--- +title: Vistas +description: Las sección Vistas describe todo lo que necesitas para configurar datos y vistas para una ruta en específico dentro de tu aplicación Nuxt.js. (Páginas, layouts y Head HTML) +--- + +> Las sección Vistas describe todo lo que necesitas para configurar datos y vistas para una ruta en específico dentro de tu aplicación Nuxt.js. (Páginas, layouts y Head HTML) + +## Pages + +Cada componente página es un componente Vue, pero Nuxt.js agrega claves especiales para hacer el desarrollo de tu aplicación universal lo más fácil posible. + +```html +<template> + <h1 class="red">Hola {{ name }}!</h1> +</template> + +<script> +export default { + data (context) { + // llamado cada vez antes de cargar el componente + return { name: 'Mundo' } + }, + fetch () { + // El métofo fetch es usado para rellenar el almacén antes de renderizar la página + }, + head () { + // Establece Meta Tags para esta Página + }, + // y más funcionalidad por descubrir + ... +} +</script> + +<style> +.red { + color: red; +} +</style> +``` + + +| Atributo | Descripción | +|-----------|-------------| +| data | Las clave más importante, tiene el mismo propósito que [Vue data](https://vuejs.org/v2/api/#Options-Data) pero puede ser asíncrona y recibe el contexto como argumento, por favor lee la [documentación de data asíncrona](/guide/async-data) para aprender cómo funciona. | +| fetch | Usado para rellenar el almacén antes de renderizar la página, es como el método data excepto que no establece el componente data. Mira [fetch en la documentación del API de Páginas](/api/pages-fetch). | +| head | Establece un Meta Tag específico para la página actual, mira [head en la documentación del API de Páginas](/api/pages-head). | +| layout | Especifica un layout definido en la carpeta `layouts`, mira [layouts en la documentación del API de Páginas](/api/pages-layout). | +| transition | Establece una transición específica para la página, mira [transición en el API de Páginas](/api/pages-transition). | +| scrollToTop | Boolean, predeterminado: `false`. Establece si desea que la página se desplace hasta la parte superior antes de ser renderizada, es usado para [rutas anidadas](/guide/routing#nested-routes). | +| validate | Función que valida una [ruta dinámica](/guide/routing#dynamic-routes). | +| middleware | Establece un middleware para esta página, el middleware se llamará antes de renderizar la página, mira [rutas middleware](/guide/routing#middleware). | + +Más información sobre el uso de las propiedades de páginas: [API de Páginas](/api) + +## Layouts + +Nuxt.js te permite extender el diseño principal o crear layouts personalizados agregandolos en el directorio de `layouts`. + +### Layout por defecto + +Puedes extender el layout principal agregando un archivo `layouts/default.vue`. + +*Asegurate de agregar el componente `<nuxt>` cuando estas creando un layout para mostrar el componente página.* + +El código fuente del layout predeterminado es: +```html +<template> + <nuxt/> +</template> +``` + +### Página de Error + +Puedes personalizar la página de error si agregas un archivo `layouts/error.vue`. + +Este layout es especial ya que puede no incluir `<nuxt/>` dentro de su plantilla. +Verás este layout como un componente mostrado cuando un error ocurre (404, 500, etc). + +El código fuente de la página de error predeterminado esta [disponible en Github](https://github.com/nuxt/nuxt.js/blob/master/lib/app/components/nuxt-error.vue). + +Ejemplo de una página de error personalizada en `layouts/error.vue`: +```html +<template> + <div class="container"> + <h1 v-if="error.statusCode === 404">Página no encontrada</h1> + <h1 v-else>Ocurrió un error</h1> + <nuxt-link to="/">Página principal</nuxt-link> + </div> +</template> + +<script> +export default { + props: ['error'] +} +</script> +``` + +### Layout Personalizado + +Cada archivo (*primer nivel*) en la carpeta `layouts` creará un layour personalizado accesible con la propiedad `layout` en el componente página. + +*Asegurate de agregar el componente `<nuxt/>` cuando estas creando un layout para mostrar el componente página.* + +Ejemplo de `layouts/blog.vue`: +```html +<template> + <div> + <div>My blog navigation bar here</div> + <nuxt/> + </div> +</template> +``` + +Y luego en `pages/posts.vue`, puedes decirle a Nuxt.js que use tu layout personalizado: +```html +<script> +export default { + layout: 'blog' +} +</script> +``` + +Más información sobre la propiedad "layout": [API de esquema(layout) de Páginas](/api/pages-layout) + +Revisa el [video de demostración](https://www.youtube.com/watch?v=YOKnSTp7d38) para verlo en acción. + +## HTML Head + +Nuxt.js uses [vue-meta](https://github.com/declandewet/vue-meta) to update the `headers` and `html attributes` of your application. + +Nuxt.js configura `vue-meta` con estas opciones: +```js +{ + keyName: 'head', // el nombre de la opción del componente donde vue-meta busca información meta. + attribute: 'n-head', // el nombre del atributo que vue-meta agrega a las etiquetas que observa + ssrAttribute: 'n-head-ssr', // el nombre del atributo que permite a vue-meta saber ue la información meta ya ha sido renderizada desde el servidor + tagIDKeyName: 'hid' // el nombre de la propiedad que vue-meta usa para determinar si sobrescribir o agregar una etiqueta +} +``` + +### Meta Tags predeterminados + +Nuxt.js te deja definir todos los meta por defecto para tu aplicación dentro de `nuxt.config.js`, usa la misma propiedad `head`: + +Ejemplo de un "viewport" personalizado con una fuente personalizada de "Google font": +```js +head: { + meta: [ + { charset: 'utf-8' }, + { name: 'viewport', content: 'width=device-width, initial-scale=1' } + ], + link: [ + { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css?family=Roboto' } + ] +} +``` + +Para conocer la lista de opciones que le puedes dar a `head`, dale una revisada en la [documentación de vue-meta](https://github.com/declandewet/vue-meta#recognized-metainfo-properties). + +Más información sobre el método head: [API Configuration head](/api/configuration-head) + +### Etiquestas Meta personalizadas para una Página + +Más información acerca del método head: [head en el API de Páginas](/api/pages-head) + +<p class="Alert">Para evitar alguna duplicación cuando usas un componente hijo, por favor dame un identificador único con el la clave `hid`, por favor [lee más acerca de esto](https://github.com/declandewet/vue-meta#lists-of-tags).</p> + +## Document + +> Puedes personalizar el "document" principal con nuxt.js + +Para ampliar la plantilla html, crea un archivo `app.html` en la raíz de tu proyecto. + +La plantilla predeterminada es: + +```html +<!DOCTYPE html> +<html {{ HTML_ATTRS }}> + <head> + {{ HEAD }} + </head> + <body {{ BODY_ATTRS }}> + {{ APP }} + </body> +</html> +``` + +Un ejemplo de agregar clases CSS condicionales para IE: + +```html +<!DOCTYPE html> +<!--[if IE 9]><html lang="en-US" class="lt-ie9 ie9" {{ HTML_ATTRS }}><![endif]--> +<!--[if (gt IE 9)|!(IE)]><!--><html {{ HTML_ATTRS }}><!--<![endif]--> + <head> + {{ HEAD }} + </head> + <body {{ BODY_ATTRS }}> + {{ APP }} + </body> +</html> +``` \ No newline at end of file diff --git a/es/guide/vuex-store.md b/es/guide/vuex-store.md new file mode 100644 index 000000000..ab9e7bb9c --- /dev/null +++ b/es/guide/vuex-store.md @@ -0,0 +1,189 @@ +--- +title: Vuex Store +description: Usar un almacén(store) para manejar el estado(state) es importante para cada aplicación grande, es por eso que nuxt.js implementa Vuex en su núcleo. +--- + +> Usar un almacén(store) para manejar el estado(state) es importante para cada aplicación grande, es por eso que nuxt.js implementa [vuex](https://github.com/vuejs/vuex) en su núcleo. + +## Activar el Almacén(store) + +Nuxt.js buscará el directorio del `almacén`, si existe, entonces: + +1. Importa Vuex +2. Agrega el módulo `vuex` en la agrupación de proveedores +3. Agrega la opción de `almacén` a la instanacia `Vue` de la raíz. + +Nuxt.js te permite tener **2 modos de almacén**, elige el que prefieras: +- **Clásico:** `store/index.js` devuelve una instancia de almacén +- **Módulos:** cada archivo `.js` dentro del directorio `store` es transformado como un [módulo con prefijo](http://vuex.vuejs.org/en/modules.html) (`index` viene a ser el módulo raíz) + +## Modo clásico + +Para activar el almacén en el modo clásico, creamos el archivo `store/index.js` y exportamos la instancia del almacén: + +```js +import Vuex from 'vuex' + +const store = new Vuex.Store({ + state: { + counter: 0 + }, + mutations: { + increment (state) { + state.counter++ + } + } +}) + +export default store +``` + +> No necesitamos instalas `vuex` ya que este viene con nuxt.js + +Ahora podemos usar `this.$store`dentro de nuestro componentes: + +```html +<template> + <button @click="$store.commit('increment')">{{ $store.state.counter }}</button> +</template> +``` + +## Modo Módulos + +> Nuxt.js te permite tener un directorio `store` con cada archivo correspondiente a un módulo. + +Si quieres esta opción, exporta el estado, mutaciónes, y acciónes en `store/index.js` en vez de una instancia de almacén: + +```js +export const state = { + counter: 0 +} + +export const mutations = { + increment (state) { + state.counter++ + } +} +``` + +Luego, puedes tener un archivo `store/todos.js`: +```js +export const state = { + list: [] +} + +export const mutations = { + add (state, text) { + state.list.push({ + text: text, + done: false + }) + }, + delete (state, { todo }) { + state.list.splice(state.list.indexOf(todo), 1) + }, + toggle (state, todo) { + todo.done = !todo.done + } +} +``` + +El almacén sería: +```js +new Vuex.Store({ + state: { counter: 0 }, + mutations: { + increment (state) { + state.counter++ + } + }, + modules: { + todos: { + state: { + list: [] + }, + mutations: { + add (state, { text }) { + state.list.push({ + text, + done: false + }) + }, + delete (state, { todo }) { + state.list.splice(state.list.indexOf(todo), 1) + }, + toggle (state, { todo }) { + todo.done = !todo.done + } + } + } + } +}) +``` + +Y en tu `pages/todos.vue`, usando el módulo `todos`: + +```html +<template> + <ul> + <li v-for="todo in todos"> + <input type="checkbox" :checked="todo.done" @change="toggle(todo)"> + <span :class="{ done: todo.done }">{{ todo.text }}</span> + </li> + <li><input placeholder="What needs to be done?" @keyup.enter="addTodo"></li> + </ul> +</template> + +<script> +import { mapMutations } from 'vuex' + +export default { + computed: { + todos () { return this.$store.state.todos.list } + }, + methods: { + addTodo (e) { + this.$store.commit('todos/add', e.target.value) + e.target.value = '' + }, + ...mapMutations({ + toggle: 'todos/toggle' + }) + } +} +</script> + +<style> +.done { + text-decoration: line-through; +} +</style> +``` + +<div class="Alert">También puedes tener módulos exportando una instanacia de almácen, tendrías que agregarlos manualmente en tu almacén.</div> + +## El Método fetch + +> El método fetch es usado para rellenar el almacén antes de que la página se arenderizada, es como el método data excepto que no establece el componente data. + +Más información sobre el método fetch: [API Pages fetch](/api/pages-fetch) + +## La Acción nuxtServerInit + +Si la acción `nuxtServerInit` es definida en el almacén, nuxt.js la llamará junto con el contexto (solo desde el lado del servidor). Es útil cuando tenemos algunos datos en el servidor que queremos llevar directamente al lado del cliente. + +Por ejemplo, digamos que tenemos sesiones en el lado del servidor y podemos acceder a los usuarios conectados a través de `req.session.user`. Para llevar al usuario autentificado a nuestro almacén, actualizamos nuestro `store/index.js` con lo siguiente: + +```js +actions: { + nuxtServerInit ({ commit }, { req }) { + if (req.session.user) { + commit('user', req.session.user) + } + } +} +``` + +> Si estas usando el modo _Modules_ de Vuex store, solo el módulo primario (en`store/index.js`) recibirá esta acción. Necesitarás encadenar tus acciones de módulo desde ahí. + +El contexto es dado a `nuxtServerInit` como el segundo argumento, es el mismo que con el método `data` o `fetch` excepto que `context.redirect()` and `context.error()` son omitidos. diff --git a/es/lang.json b/es/lang.json new file mode 100644 index 000000000..488376398 --- /dev/null +++ b/es/lang.json @@ -0,0 +1,50 @@ +{ + "iso": "es", + "links": { + "api": "API", + "blog": "Blog", + "chat": "Chat", + "documentation": "Documentación", + "download": "Descarga", + "examples": "Ejemplos", + "ecosystem": "Ecosistema", + "faq": "FAQ", + "get_started": "empezar", + "github": "Github", + "guide": "Guía", + "homepage": "Página principal", + "live_demo": "Demostración en vivo", + "live_edit": "Editar en vivo", + "twitter": "Twitter", + "vuejs": "Vue.js", + "vue_jobs": "Vue Jobs" + }, + "text": { + "an_error_occured": "Ocurrió un error", + "api_page_not_found": "API page not found", + "example_file": "Archivos ejemplo", + "please_wait": "Por favor, espera...", + "please_define_title": "Por favor especificar un título en la parte delantera", + "please_define_description": "Por favor, especificar una descripción en la parte delantera", + "search": "Buscar", + "version": "Versión" + }, + "homepage": { + "title": "Aplicaciones Universales con Vue.js", + "meta": { + "title": "Nuxt.js - Universal Vue.js Applications", + "description": "Nuxt.js es un framework mínimo para crear aplicaciones Vue.js con server \"side rendering\", \"code-splitting\", \"hot-reloading\", \"static generation\" y más!" + } + }, + "footer": { + "authors": "Made by Chopin Brothers" + }, + "guide": { + "release_notes": "Release Notes", + "contribute": "¿Encontraste un error o quieres contribuir con la documentación?", + "edit_on_github": "¡Edita esta página en Github!" + }, + "examples": { + "source_code": "Código fuente" + } +}