diff --git a/examples/custom-layouts/README.md b/examples/custom-layouts/README.md index a829a56d85..21ecee452c 100644 --- a/examples/custom-layouts/README.md +++ b/examples/custom-layouts/README.md @@ -1,60 +1,3 @@ # Layouts -> Nuxt.js allows you to extend the main layout or create custom layout by adding them in the `layouts/` directory - -## layouts/default.vue - -You can extend the main layout by adding a `layouts/default.vue` file. - -*Make sure to add the `` component when creating a layout to display the page component.* - -The default layout source code is: -```html - -``` - -## layouts/error.vue - -You can customize the error page by adding a `layouts/error.vue` file. - -This layout is special since your should not include `` inside its template, see this layout as a component displayed when an error occurs (404, 500, etc). - -The default error page source code is available on: https://github.com/nuxt/nuxt.js/blob/master/lib/app/components/nuxt-error.vue - -## layouts/*.vue - -See the [demonstration video](https://www.youtube.com/watch?v=YOKnSTp7d38). - -Every file (*first level*) in the `layouts/` directory will create a custom layout accessible with the `layout` property in the page component. - -*Make sure to add the `` component when creating a layout to display the page component.* - -Example of `layouts/blog.vue`: -```html - -``` - -And then in `pages/posts.vue` I can tell Nuxt.js to use this custom layout: -```html - -``` - -## Demo - -```bash -npm install -npm run dev -``` - -Go to [http://localhost:3000](http://localhost:3000) and navigate trough the app. To see the custom error page: [http://localhost:3000/404](http://localhost:3000/404) +https://nuxtjs.org/examples/layouts diff --git a/examples/custom-loading/README.md b/examples/custom-loading/README.md index 84b108ca51..f69dd97ea5 100644 --- a/examples/custom-loading/README.md +++ b/examples/custom-loading/README.md @@ -1,106 +1,3 @@ # Custom loading with Nuxt.js -> 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 Nuxt.js progress bar - -If you don't want to display the progress bar between the routes, just add `loading: false` in your `nuxt.config.js` file: -```js -// nuxt.config.js -module.exports = { - loading: false -} -``` - -## Customize Nuxt.js progress bar - -Here are the properties you can customize for Nuxt.js 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 during 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. | - -Example: -```js -// nuxt.config.js -module.exports = { - loading: { - color: 'blue', - height: '5px' - } -} -``` - -## Create a custom loading component - -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. - -Your custom component will be called by Nuxt.js, so make sure your component exposes some of theses methods: - -| Method | Required | Description | -|--------|----------|-------------| -| `start()` | Required | Called when a route changes, this is here where you should show your component. | -| `finish()` | Required | Called when a route is loaded (and data fetched), this is here where you should hide your component. | -| `fail()` | *Optional* | Called when a route could not be loaded (failed to fetch data for example). | -| `increase(num)` | *Optional* | Called during loading the route component, `num` is an Integer < 100. | - - -Example: -```js -// nuxt.config.js -module.exports = { - loading: 'components/loading.vue' -} -``` - -And then, in `components/loading.vue`: -```html - - - - - -``` - -## Demo - -```bash -npm install -npm start -``` - -Go to [http://localhost:3000](http://localhost:3000) and navigate trough the app. +https://nuxtjs.org/examples/custom-loading diff --git a/examples/custom-routes/README.md b/examples/custom-routes/README.md index a6a85d97ad..3a95b0d8bf 100644 --- a/examples/custom-routes/README.md +++ b/examples/custom-routes/README.md @@ -1,185 +1,3 @@ -# Defining custom routes with Nuxt.js +# Custom Routes with Nuxt.js -> Nuxt.js is based on `vue-router` and let you to defined custom routes easily :rocket: - -## Concept - -Nuxt.js generates automatically the `vue-router` configuration according to your file tree of `.vue` files inside the `pages/` directory. - -## Basic routes - -This file tree: - -```bash -pages/ ---| team/ ------| index.vue ------| about.vue ---| index.vue -``` - -will automatically generate: - -```js -router: { - routes: [ - { - name: 'index', - path: '/', - component: 'pages/index.vue' - }, - { - name: 'team', - path: '/team', - component: 'pages/team/index.vue' - }, - { - name: 'team-about', - path: '/team/about', - component: 'pages/team/about.vue' - } - ] -} -``` - -## Dynamic routes - -To define a dynamic route with a param, you need to define a `.vue` file **prefixed by an underscore**. - -This file tree: - -```bash -pages/ ---| users/ ------| _id.vue ------| index.vue -``` - -will automatically generate: - -```js -router: { - routes: [ - { - name: 'users', - path: '/users', - component: 'pages/users/index.vue' - }, - { - name: 'users-id', - path: '/users/:id', - component: 'pages/users/_id.vue' - } - ] -} -``` - -### Additional feature: validate (optional) - -Nuxt.js lets you define a validator function 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 - -``` - -## Nested Routes (children) - -To define a nested route, you need to create a `.vue` file with the **same name as the directory** which contain your children views. -> Don't forget to put `` inside your parent `.vue` file. - -This file tree: - -```bash -pages/ ---| users/ ------| _id.vue ---| users.vue -``` - -will automatically generate: - -```js -router: { - routes: [ - { - path: '/users', - component: 'pages/users.vue', - children: [ - { - path: ':id', - component: 'pages/users/_id.vue', - name: 'users-id' - } - ] - } - ] -} -``` - -## Dynamic Nested Routes - -This file tree: - -```bash -pages/ ---| posts/ ------| _slug/ ---------| _name.vue ---------| comments.vue ------| _slug.vue ------| index.vue ---| posts.vue -``` - -will automatically generate: - -```js -router: { - routes: [ - { - path: '/posts', - component: 'pages/posts.vue', - children: [ - { -          path '', - component: 'pages/posts/index.vue', - name: 'posts' - }, - { - path: ':slug', - component: 'pages/posts/_slug.vue', - children: [ - { - path: 'comments', - component: 'pages/posts/_slug/comments.vue', - name: 'posts-slug-comments' - }, - { - path: ':name', - component: 'pages/posts/_slug/_name.vue', - name: 'posts-slug-name' - } - ] - } - ] - } - ] -} -``` - -## Demo - -```bash -npm install -npm start -``` - -Go to [http://localhost:3000](http://localhost:3000) and navigate through the pages. +https://nuxtjs.org/examples/custom-routes diff --git a/examples/global-css/README.md b/examples/global-css/README.md index 5b70bd5591..94f73bf46f 100644 --- a/examples/global-css/README.md +++ b/examples/global-css/README.md @@ -1,46 +1,3 @@ # Global CSS with Nuxt.js -> Nuxt.js let you define the CSS files/modules/libraries you want to set as globals (included in every pages). - -## Usage - -In `nuxt.config.js` file, add the CSS resources: - -```js -const { resolve } = require('path') - -module.exports = { - css: [ - // Load a node.js module - 'hover.css/css/hover-min.css', - // node.js module but we specify the lang - { src: 'bulma', lang: 'sass' }, - // Css file in the project - // It is important to give an absolute path - resolve(__dirname, 'css/main.css') - ] -} -``` - -## Demo - -To see the demo working: -```bash -npm install -npm run dev -``` - -Go to [http://localhost:3000](http://localhost:3000) and navigate inside the app. - -## Production - -In production, they will be minified and extracted in a file named `styles.css` and added in the `` of the page. - -To launch the demo in production mode so you can see the `` populated with the `` tag: - -```bash -npm run build -npm start -``` - -Go to [http://localhost:3000](http://localhost:3000) and check the source code. +https://nuxtjs.org/examples/global-css diff --git a/examples/head-elements/README.md b/examples/head-elements/README.md index 6468bf8e96..1b7d3962d2 100644 --- a/examples/head-elements/README.md +++ b/examples/head-elements/README.md @@ -1,85 +1,3 @@ # Updating headers with Nuxt.js -Nuxt.js uses [`vue-meta`](https://github.com/declandewet/vue-meta) to update the `headers` and `html attributes` of your applications. - -Nuxt.js configures `vue-meta` with these options: -```js -{ - keyName: 'head', // the component option name that vue-meta looks for meta info on. - attribute: 'n-head', // the attribute name vue-meta adds to the tags it observes - ssrAttribute: 'n-head-ssr', // the attribute name that lets vue-meta know that meta info has already been server-rendered - tagIDKeyName: 'hid' // the property name that vue-meta uses to determine whether to overwrite or append a tag -} -``` - -## Updating the title - -To update the title of the page, just add `head.title` in your page component. - -`pages/index.vue` -```html - - - -``` - -## Meta tags and more - -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). - -## Using `data` values inside `head` - -You might want to use the component data to display different headers, like a post title for example. Just use `head` as a function and you can use `this` inside to access your component data. - -Example of displaying the post title: -```html - -``` - -## Defaults metas - -Nuxt.js let you define all the defaults metas for your application inside the `nuxt.config.js`, use the same field `head`: -```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' } - ] - } -} -``` - -## Demo - -```bash -npm install -npm start -``` - -Go to [http://localhost:3000](http://localhost:3000) and navigate trough the app. Notice how the page's title changes between the pages and is also server-side rendered. +https://nuxtjs.org/examples/seo-html-head diff --git a/examples/hello-world/README.md b/examples/hello-world/README.md new file mode 100644 index 0000000000..d64ba5270a --- /dev/null +++ b/examples/hello-world/README.md @@ -0,0 +1,3 @@ +# Hello World with Nuxt.js + +https://nuxtjs.org/examples diff --git a/examples/plugins-vendor/README.md b/examples/plugins-vendor/README.md index e2da6dc42d..d86e3dcc5a 100644 --- a/examples/plugins-vendor/README.md +++ b/examples/plugins-vendor/README.md @@ -1,76 +1,3 @@ -# Using external modules and plugins with nuxt.js +# Using external modules and plugins with Nuxt.js -## Configuration: `build.vendor` - -> Nuxt.js allows you to 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) - -To add a module/file inside the vendor bundle, add the `build.vendor` key inside `nuxt.config.js`: -```js -const { join } = require('path') - -module.exports = { - build: { - vendor: [ - 'axios', // node module - join(__dirname, './js/my-library.js') // custom file - ] - } -} -``` - -## Configuration: `plugins` - -> Nuxt.js allows you to define js plugins to be ran before instantiating the root vue.js application - -I want to use [vue-notifications](https://github.com/se-panfilov/vue-notifications) to validate the data in my inputs, I need to setup the plugin before launching the app. - -File `plugins/vue-notifications.js`: -```js -import Vue from 'vue' -import VueNotifications from 'vue-notifications' - -Vue.use(VueNotifications) -``` - -Then, I add my file inside the `plugins` key of `nuxt.config.js`: -```js -const { join } = require('path') - -module.exports = { - build: { - vendor: ['vue-notifications'] - }, - plugins: [ '~plugins/vue-notifications' ] -} -``` - -I use `~plugins` here because nuxt.js create an alias for the `plugins/` folder, it's equivalent to: `join(__dirname, './plugins/vue-notifications.js')` - -I added `vue-notifications` in the `vendor` key to make sure that it won't be included in any other build if I call `require('vue-notifications')` in a component. - -### Only in browser build - -Some plugins might work only in the browser, for this, you can use the `process.BROWSER_BUILD` variable to check if the plugin will run from the server or from the client. - -Example: -```js -import Vue from 'vue' -import VueNotifications from 'vue-notifications' - -if (process.BROWSER_BUILD) { - Vue.use(VueNotifications) -} -``` - -### Only in server build - -In case you need to require some libraries only for the server, you can use the `process.SERVER_BUILD` variable set to `true` when webpack is creating the `server.bundle.js` file. - -## Demo - -```bash -npm install -npm start -``` - -Go to [http://localhost:3000](http://localhost:3000) and navigate trough the pages. +https://nuxtjs.org/examples/plugins diff --git a/examples/routes-transitions/README.md b/examples/routes-transitions/README.md index f5ed57784a..fe38a76062 100644 --- a/examples/routes-transitions/README.md +++ b/examples/routes-transitions/README.md @@ -1,151 +1,3 @@ # Routes transitions with Nuxt.js -> Nuxt.js uses the [``](http://vuejs.org/v2/guide/transitions.html#Transitioning-Single-Elements-Components) component to let you create amazing transitions/animations between your routes. - -## Usage - -🎬 [Demonstration video](https://www.youtube.com/watch?v=RIXOzJWFfc8) - -**Nuxt.js default transition name is `page`.** - -To add a fade transition to every page of your application, we need a CSS file that is shared across all our routes, so we start by creating a file in the `assets/` folder. - -`assets/main.css`: -```css -.page-enter-active, .page-leave-active { - transition: opacity .5s -} -.page-enter, .page-leave-active { - opacity: 0 -} -``` - -We add its path in our `nuxt.config.js` file: -```js -module.exports = { - css: [ - 'assets/main.css' - ] -} -``` - -And voilà! A nice fade animation will be shown between every routes. - -## The `transition` key - -You can update the defaults transition settings by adding the `transition` key in you `nuxt.config.js` file. - -```js -module.exports = { - transition: 'test' - // or - transition: { - name: 'test', - mode: 'out-in' - } -} -``` - -Nuxt.js will use these settings to set the component as follows: -```html - -``` - -To learn more about the Vue.js `` component: http://vuejs.org/v2/guide/transitions.html - -The following properties that the `transition` key 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` | See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | -| `enterActiveClass` | String | `n/a` | See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | -| `leaveClass` | String | `n/a` | See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | -| `leaveActiveClass` | String | `n/a` | See [Vue.js documentation](https://vuejs.org/v2/guide/transitions.html#Custom-Transition-Classes) | - -*Note: if the `transition` key is set as a string, it will be used as the `transition.name`.* - -You can also define methods in the `transition`, these are for the [JavaScript hooks](https://vuejs.org/v2/guide/transitions.html#JavaScript-Hooks): - -- `beforeEnter: function (el) { ... }` -- `enter: function (el, done) { ... }` -- `afterEnter: function (el) { ... }` -- `enterCancelled: function (el) { ... }` -- `beforeLeave: function (el) { ... }` -- `leave: function (el, done) { ... }` -- `afterLeave: function (el) { ... }` -- `leaveCancelled: function (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.* - -## Custom transition on a specific route - -To define a custom transition for a specific route, simply add the `transition` key to the page component: - -`pages/about.vue`: -```html - - - -``` - -And then we add the CSS animation for this custom transition: -```css -/* assets/main.css */ -.bounce-enter-active { - animation: bounce-in .8s; -} -.bounce-leave-active { - animation: bounce-out .5s; -} -@keyframes bounce-in { - 0% { transform: scale(0) } - 50% { transform: scale(1.5) } - 100% { transform: scale(1) } -} -@keyframes bounce-out { - 0% { transform: scale(1) } - 50% { transform: scale(1.5) } - 100% { transform: scale(0) } -} -``` - -*Note: you can also the set `transition` key as an object in page components* - -## Dynamic transition - -To create a dynamic transition between two route depending on the route parameters, set the `transition` key as a `function`. - -Example: -`pages/posts.vue` -```html - -``` - -## Demo - -```bash -npm install -npm run dev -``` - -Go to [http://localhost:3000](http://localhost:3000) and navigate through the pages. +https://nuxtjs.org/examples/routes-transitions diff --git a/examples/vuex-store-2/README.md b/examples/vuex-store-2/README.md deleted file mode 100644 index 8146795f6c..0000000000 --- a/examples/vuex-store-2/README.md +++ /dev/null @@ -1,94 +0,0 @@ -# Nuxt.js with Vuex 2 - -> Using a store to manage the state is important to every big application, that's why nuxt.js implement Vuex in its core. - -> Alternative way of creating a store modularly. - -## Activating the store - -Nuxt.js will look for the `./store/` directory, if it exists, its will import and use Vuex. If there is no `./store/index.js` file that returns a store, Nuxt.js will go through all files of the `./store/` directory and create a store with a module for each file (`./store/index.js` being "root" module). - -## Create the store folder - -Let's create a file `store/index.js`: - -```js -export const state = { counter: 0 } - -export const mutations = { - increment (state) { - state.counter++ - } -} -``` - -and -`store/todos.js`: - -```js -export const state = { - list: [] -} - -export const 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 - } -} -``` - -> We don't need to install `Vuex` since it's shipped with nuxt.js - -## Voilà ! - -We can now use `this.$store` inside our `.vue` files. - -```html - -``` - -The store will be as such: -```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 - } - } - } - } -}) -``` diff --git a/examples/vuex-store-modules/README.md b/examples/vuex-store-modules/README.md new file mode 100644 index 0000000000..f248cfd42b --- /dev/null +++ b/examples/vuex-store-modules/README.md @@ -0,0 +1,3 @@ +# Nuxt.js with Vuex via File API + +https://nuxtjs.org/guide/vuex-store#modules-files diff --git a/examples/vuex-store-2/package.json b/examples/vuex-store-modules/package.json similarity index 100% rename from examples/vuex-store-2/package.json rename to examples/vuex-store-modules/package.json diff --git a/examples/vuex-store-2/pages/about.vue b/examples/vuex-store-modules/pages/about.vue similarity index 100% rename from examples/vuex-store-2/pages/about.vue rename to examples/vuex-store-modules/pages/about.vue diff --git a/examples/vuex-store-2/pages/index.vue b/examples/vuex-store-modules/pages/index.vue similarity index 100% rename from examples/vuex-store-2/pages/index.vue rename to examples/vuex-store-modules/pages/index.vue diff --git a/examples/vuex-store-2/pages/todos.vue b/examples/vuex-store-modules/pages/todos.vue similarity index 100% rename from examples/vuex-store-2/pages/todos.vue rename to examples/vuex-store-modules/pages/todos.vue diff --git a/examples/vuex-store-2/store/index.js b/examples/vuex-store-modules/store/index.js similarity index 100% rename from examples/vuex-store-2/store/index.js rename to examples/vuex-store-modules/store/index.js diff --git a/examples/vuex-store-2/store/todos.js b/examples/vuex-store-modules/store/todos.js similarity index 100% rename from examples/vuex-store-2/store/todos.js rename to examples/vuex-store-modules/store/todos.js diff --git a/examples/vuex-store/README.md b/examples/vuex-store/README.md index 4bf9cbec9e..96aa014061 100644 --- a/examples/vuex-store/README.md +++ b/examples/vuex-store/README.md @@ -1,83 +1,3 @@ # Nuxt.js with Vuex -> Using a store to manage the state is important to every big application, that's why nuxt.js implement Vuex in its core. - -## Activating the store - -Nuxt.js will try to `require('./store/index.js')`, if exists, it will import `Vuex`, add it to the vendors and add the `store` option to the root `Vue` instance. - -## Create the store folder - -Let's create a file `store/index.js`: - -```js -import Vue from 'vue' -import Vuex from 'vuex' - -Vue.use(Vuex) - -const store = new Vuex.Store({ - state: { - counter: 0 - }, - mutations: { - increment (state) { - state.counter++ - } - } -}) - -export default store -``` - -> We don't need to install `Vuex` since it's shipped with nuxt.js - -## Voilà ! - -We can now use `this.$store` inside our `.vue` files. - -```html - -``` - -## fetch (context) - -> Used to fill the store before rendering the page - -The `fetch` method, *if set*, is called every time before loading the component (*only if attached to a route*). It can be called from the server-side or before navigating to the corresponding route. - -The `fetch` method receives the 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. - -For example: -```js -export default { - fetch ({ store, params }) { - return axios.get('http://my-url') - .then((res) => { - store.commit('setUser', res.data) - }) - } -} -``` - -## Context - -To see the list of available keys in `context`, take a look at [this documentation](https://github.com/nuxt/nuxt.js/tree/master/examples/async-data#context). - -## Action `nuxtServerInit` - -If we define the action `nuxtServerInit` in our store, Nuxt.js will call it with the context. It can be useful when having some data on the server we want to give directly to the client-side, for example, the authenticated user: -```js -// store/index.js -actions: { - nuxtServerInit ({ commit }, { req }) { - if (req.authUser) { - commit('user', req.authUser) - } - } -} -``` - -The context given to `nuxtServerInit` is the same as the `data` of `fetch` method except `context.redirect()` and `context.error()` are omitted. +https://nuxtjs.org/examples/vuex-store diff --git a/examples/with-ava/Readme.md b/examples/with-ava/Readme.md index cd449998ab..cd49ff5647 100755 --- a/examples/with-ava/Readme.md +++ b/examples/with-ava/Readme.md @@ -1,25 +1,3 @@ -## Add testing to your `nuxt` app using `ava` and `jsdom` +## Testing your Nuxt.js Application -[`ava`](https://github.com/avajs/ava) is a powerful JavaScript testing framework, mixed with [`jsdom`](https://github.com/tmpvar/jsdom), we can use them to do end-to-end testing easily for `nuxt` applications. - -```bash -npm install --save-dev ava jsdom -``` - -Add test script to the `package.json` - -__package.json__ - -```javascript -// ... -"scripts": { - "test": "ava", -} -// ... - -``` - -Launch the tests: -```bash -npm test -``` +https://nuxtjs.org/examples/testing