Feedback & Improvements

manniL commented 5 years ago

Hey folks!

Please give feedback regarding the documentation of Nuxt.js in this issue.

Some things you could cover (but don't have to):

Content

What is unclear/hard to understand/could be better explained?
What is missing in the docs?
What is explained too verbose?
Which examples would you like to see?
Which parts should be structured better? How?

Style

Do you have problems reading the docs (font size, font style, ...)

And so on!

We'd love to hear your feedback ☺️ ❤️

大家好：

希望各位可以在这个Issue中提供与Nuxt.js文档相关的反馈。

您的评论可以涉及（不必包含所有）：

内容

有哪些内容不清楚或难以理解，可以如何完善？
文档中缺少什么内容？
有那些表达太冗长了？
您希望文档包含哪些例子？
哪些部分可以完善？有什么建议？

样式

阅读文档时遇到问题（字体大小，字体样式......）

当然也欢迎提出其他方面的想法。

我们将很期待您的反馈☺️❤️

manniL commented 5 years ago

cc @lucasfischer @sp0ken @duruld

sp0ken commented 5 years ago

Style is clear enough for me.

As I said in #4681, generate mode is often left behind. For example it is never mentionned how asyncData and fetch behave when using it. Debugging an error happening during the generation is also quite tricky for a lack of logging method available.

falstack commented 5 years ago

Hello members of the nuxt team

I found that the synchronization of nuxt's Chinese document translation is very slow and basically can't be used for reference. Our team has tried both the Vue SSR's native solution and the nuxt solution. Thanks to the nuxt framework. It saves us a lot of costs. Although our products are not yet profitable, but we want to do some work for the translation of Chinese documents for nuxt, can you get your consent?

manniL commented 5 years ago

Hey @falstack 👋

of course! We are happy to accept PRs to this repository which improve the Chinese docs ☺️

mxrlkn commented 5 years ago

I would like to see docs and examples on how to deploy nuxt as a lambda function to aws lambda, google cloud functions, netlify functions etc.

syffs commented 5 years ago

if you're opened to suggestions, here are some subjects which I missed at some point throughout my nuxt experience, feel free to select what makes more sense:

nuxt in production: examples, guidelines, best practices & recommendation
- tools / monitoring
- ci/cd
- deployment patterns/examples for static/small/medium/large applications: let's say you want to build a popular high traffic website, what would you recommend/implement regarding
  - architecture
  - services (hosting, cdn, etc...)
  - database engine
  - libraries
testing: comprehensive and advanced example/documentation on testing your nuxt application

PJLindsay commented 5 years ago

Would like an explicit example and some minor fine tuning of the documentation of the "Cookie login flow" Vs JWT Auth flow under local strategy here: https://auth.nuxtjs.org/reference/schemes/local

This would be extremely useful for newcomers to nuxt. i.e. exactly what your local strategy settings should be, such as

// Use these settings for Cookie Auth flow tokenRequired: false, tokenType: false

I am afk for another day or two but I can make a PR tomorrow if someone doesn't want to wait

hecktarzuli commented 5 years ago

Pasted from https://github.com/nuxt/nuxt.js/issues/4681

Documentation needs a lot more work. Hooks, templates areas especially.
It would be nice to have more guides/documentation around server side things too. For myself & my team it took us a lot of toying around to figure out what a middleware acts like, what plugins really do and how to use serverMiddleware etc.. If you don't start with nuxt and are used to doing things the SPA way, transitioning to nuxt generates a LOT of questions like:
Ok, this 'thing' loads once on start up, but runs this function on every hit
Oh crap, why is created() being called on EVERY hit now??!.. 4h later, oh, it's because of an undocumented key property that needs to be set somewhere. It almost looks related to transitions.. How do we disable transitions? etc..

studnitz commented 5 years ago

I agree with most of the things already listed here, but I'd like to add some things to the conversation, which I think could help many people, especially those new to Nuxt:

Content

Guide

Listing API/features vs. guiding someone how to accomplish something

I think the guide at the moment could do a better job of actually guiding a (new) user through the process of incrementally building a nuxt application. For example the entries in the Getting Started section of the guide are:

Current "Getting Started" Section of the Guide

Installation
Directory Structure
Configuration
Routing
Views
Async Data
Assets
Plugins
Modules
Vuex Store
TypeScript Support
Commands and Deployment
Development Tools

I think this is a bit much for a Getting Started part of a guide. Every entry is obviously important in its own regard, but this is more of an overview of the many awesome features of Nuxt. The module section for example shows how to create a module from scratch, but does not list any of the many useful modules that already exist, which in my opinion would make more sense for a new user.

I think what makes Nuxt so awesome is that you get already so much things without adding many lines of code: Need a new page? Just drop a new page.vue file in the pages directory, need to make an API request? yarn add @nuxtjs/axios and add a line to the nuxt.config.js, want to add V-Calendar, which only works client-side? Create a file v-calendar.client.js and add 2 lines for installing the Vue Plugin and so on.

So my suggestion would be to actually reflect that in the nuxt guide focusing more what we want to accomplish and how to do it instead of just listing and explaining the features, I could imagine a structure somewhat like this for the Getting Started guide with the concepts being taught in parantheses:

Propsed "Getting Started" section

Installation
Writing Your First Nuxt App
- Hello World with an image (the aliases, /components and /assets)
- Adding a new page (/pages, routing and NuxtLink)
- Installing a vue component (/plugins and nuxt.config.js)
- Making async API requests with axios (modules and asyncData)
- Adding a dark mode (/layouts)
- Changing the title and adding meta-tags (head and meta of pages/nuxt.config.js)
- Deploy (nuxt build vs nuxt generate, deploying to netlify/now)
Directory structure is configuration (like current "directory structure" page)
Further configuration with nuxt.config.js (like current "configuration" page,
Testing your Nuxt app

Then maybe another section like "core nuxt features", which would inhibit most of the current "Getting Started" pages but also with more of a focus of what we want to accomplish instead of just listing the name of the API.

"Core Nuxt Features" in the Guide

Adding a Vuex store
- Directory structure is naming (/store and namespaced vuex modules)
- Making async API requests (fetch)
- Initializing the store with server-data (nuxtServerInit)
Routing
etc.

Examples and documentation feel disconnected

The examples are not incorporated into the Guide/API, which would make tinkering after reading the documenation more accesible and easy.

Other things

The code examples in the documentation all use kebab-case, although I think you've been favoring using PascalCase (as seen in the examples).
Having a reference table like for the context for the nuxt.config.js/configuration part (maybe grouped by concern) and the pages API would be certainly useful in my opinion

Style

As everybody knows, style is a really subjective topic, but I think there a few things that could improve the readibility and legibility of the documentation.

Give the content a fixed width, so that line length stays around 75 - 100 chars per line
Use a dark theme for code highlighting in examples, I personally find that it makes skimming a page much easier. 😃 The theme in the CodeSandbox examples is really good.
Alert components don't have an accessible color contrast (green and orange one)
- This could be fixed like this

Closing Remarks

Okay, this got a little bit longer than expected, I hope that's okay. 😅

I love Nuxt and use it almost exclusively now at work as I have introduced it there and I would be happy to contribute to the docs and also help to implement these suggestions if they are accepted. :)

Keep up the good work! 😃

phartikainen commented 5 years ago

Please improve documentation / status of the module and community modules. Blog module seems to be from 2017 and apparently not working out of the box with very little documentation.

farzadso commented 5 years ago

@phartikainen Which part do you mean precisely? Can you please provide a link?

phartikainen commented 5 years ago

Official modules listed here: https://github.com/nuxt-community/awesome-nuxt#modules

There is a blog module: https://github.com/nuxt-community/blog-module

It does not work out of the box and it's 2 years old

manniL commented 5 years ago

@phartikainen Hey 👋

awesome-nuxt is a community-curated resource list.

Anyway, you are right, we are cleaning up the modules soon and either update or abandon old ones 👍

phartikainen commented 5 years ago

Yeah I’m aware of that, but that is the only blog-related module listed

-- Pekka Hartikainen www.pekkahartikainen.fi Twitter: @pastorator

On 21 February 2019 at 12.00.16, Alexander Lichter (notifications@github.com) wrote:

@phartikainen https://github.com/phartikainen Hey 👋

awesome-nuxt is a community-curated resource list.

Anyway, you are right, we are cleaning up the modules soon and either update or abandon old ones 👍

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/nuxt/docs/issues/1078#issuecomment-465937510, or mute the thread https://github.com/notifications/unsubscribe-auth/ABNrwRgMGpt-Dt8yyj6N9O2SrBaczXjlks5vPm4wgaJpZM4Zob4A .

danchristian commented 5 years ago

I think the Nuxt documentation could do a better job at explaining when to use which mode/output for the different types of generic applications that exist. As there is SSR, SPA and then Static. You can also have an SSR application that selectively has SPA mode and vice versa. You can have a Static website with SPA using generate.exclude. You can also just have a Static website that has simple API calls to a DB aka JAMstack. It can get quite confusing.

A lot of the turorials of Nuxt are using the generate part to build content blogs as they are easy examples, but this maybe belittles how far you can get with the JAMstack.

Google have a helpful page regarding this and the Gatsby docs have a section that explains the different use cases.

I think the Nuxt documentation could be even more helpful for people coming to Nuxt for the first time. For example, here are 6 different types of website/application you might build and here is the reccomended way to build them (SPA, SSR, Static etc) and why.

xibman commented 5 years ago

Hi All,

It think something very unclear in the doc is how AsyncData merge data with the internal page data when you use query watcher.

Because it merge data that come from asyncData result with the original data of the page, not the current state.

hrastnik commented 5 years ago

I personally struggled a lot to grasp how the commands nuxt generate and nuxt build work and how their behaviour changes when the --spa flag is appended. I am still only about 95% sure that nuxt generate --spa and nuxt build --spa produce the same output. This only raises more questions - why does the generate command even allow the --spa flag?

The docs could explain all those modes better, also explain how does the --spa and --universal flags behave when nuxt.config.js has mode set to something different? Who wins? Then there's the --modern flag, so that's even more things to consider.

Another thing is the errors one encounters when dealing with server side rendering and libraries that don't support it out of the box.

I really love Nuxt and I actually believe it could be the standard for creating web apps and web sites. I just hate to think someone could stop using it because of some easily fixable error that s/he couldn't find the solution to in the docs. (almost happened to a colleague - solution was to add ssr:false to a plugin)

codeofsumit commented 5 years ago

I love nuxt! Thanks so much for your work on this. I've recently started a new project so here are a few things I think are missing in the docs:

devModules documentation
How to deploy to now v2: the nuxt/now-builder is not mentioned
Deploy to ZEIT in a monorepo (not two nuxt apps, but one app with many microservices)

Thanks again for this great framework 🙏

minijaypark commented 5 years ago

Hi, I wonder if this is a problem, but I just found that the links in the translated documents are redirected to English one. For example, I was reading Routing document page in Korean (https://ko.nuxtjs.org/guide/routing/) and if I click the link to 'transition', it is connected to 'https://vuejs.org/v2/guide/transitions.html#Transitioning-Single-Elements-Components', which is original English version of transition document, even if it has a Korean version. This does not apply to every page and link, but it's kind of bothersome sometimes. Plus, most of the translated documents' main page are not translated in each languages!(Only Japanese is translated) Thank you!

farzadso commented 5 years ago

@minijaypark They're two different sites, but I think the link can be dynamic based on the language.

richardeschloss commented 5 years ago

Hi Nuxt team, First the good: really great work, it makes it fun to work with Vue. I like this framework a lot. The docs are helpful, but some minor changes I think can make it more enjoyable for the new person: 1) The sidebar used to be scroll-able (I think just a few days ago) but now it doesn't seem to be. I think it's cool that the side content grays out when the main content is in focus, however, I liked being able to scroll the sidebar. Especially on the Examples page. 1b) Also, if I reduce the size of my browser window (Chrome) to say 50%, the sidebar content disappears without a hamburger icon to let me access it.

I appreciate your help. I'm still learning.

manniL commented 5 years ago

@richardeschloss Thanks for the feedback!

The 1st issue got fixed by @CurtisBelt :relaxed: https://github.com/nuxt/nuxtjs.org/pull/234

For your 2nd issue, there is a menu at the bottom:

richardeschloss commented 5 years ago

Wow that was fast! Thanks guys for doing this on a Saturday!

ubershmekel commented 5 years ago

Nuxt page life cycle and vue-class-component had me confused for weeks. I tried all kinds of things like like marking the data members as ! with no default value, which caused them to not be reactive, I set the default values which caused them to be reset back to default when the route changed, I tried to modify them in the created method, but that wasn't called. I'm still not sure I have everything set up correctly. I have reactive data that is defined by the route, and when it changes, I want it to show up in the route. The simplest example is a search box that updates the URL query, and the results on the page. Here's the struggle:

  @Watch('$route', { immediate: true, deep: true })
  onUrlChange(to: any, from: any) {
    // Gotcha! `this` is about to be reset, don't modify it here at all...
    this.query = to.query.q;
  }

  @Watch("query")
  onQueryChanged(newQuery: string, oldQuery: string) {
    this.$router.replace({path: this.$route.path, query: { q: newQuery }});
  }

It's just unclear which way should the information flow and how. What I ended up doing was not modifying this.query in the route watch, but instead modifying it in the asyncData method using context.route.query.q. Because every route change would later cause the page to reset with the default values. I assumed that if I stay on the same page, all my data would stay the same - a few days in - I realized that's not the case at all and could not find any docs about it.

With all that backstory - it might make sense to describe how this kind of thing should be done. And along that it would help to see a page end-to-end life cycle diagram or list. This is what should be included as far as I'm aware:

beforeRouteUpdate is called when the route that renders this component has changed, but this component is reused in the new route, before the value of the $route object actually changes. Using the beforeRouteUpdate navigation guard, you can determine whether or not you want to prevent the route from changing or go to a different route entirely.
@Watch('$route', { immediate: true, deep: true }) called when the route changes - though you have access to this know that your changes won't last long because the page is about to reset them.
asyncData, even if not defined - will cause all the page data members to be reset to default or the data method, even though the vue life cycle (created/mounted) is NOT called when the route changes but the page is the same.
fetch
if it's not the same page - created
if it's not the same page - mounted

richardeschloss commented 5 years ago

Hi Nuxt docs team, I think I can provide something helpful to: Routing/transitions. I got tripped up by something that might trip others.

I think it's great that the top of the page recommends using <nuxt-link> tags to switch between pages. However, I think it's important to stress that in order for page transitions to work right, <nuxt-link> tags (with the "to" prop set) appear to be required. I.e., using <a> tags and setting href will switch pages but won't trigger the animation.

If people use bootstrap-vue, some of the examples, such as <b-nav-item>, use href, and Nuxt beginners may be tempted to copy-n-paste examples from their website and then scratch their head for awhile. Further reading on the bootstrap-vue docs reveals that the "to" prop in their components should be used instead of href.

leesmith commented 5 years ago

I think the deployment to AWS w/ S3 + Cloudfront page is far too complicated. If you use AWS, you'll most likely want to use the AWS CLI. Using the AWS CLI, deploying the dist folder to an S3 bucket AND invalidating the Cloudfront distribution is a few CLI commands. I would not follow all the gulp rigmarole as described.

Here's my deploy.sh that syncs the dist folder and invalidates the Cloudfront distribution: https://gist.github.com/leesmith/181dec1332a3c262f4d8a948a0afa4e1

coreysyms commented 5 years ago

@leesmith is ABSOLUTELY right. AWS is death by 1000 cuts anyhow, using his method is so much simpler... PRO TIP: if you're on Mac, for the love of all things holy, install AWS CLI with HomeBrew

VesterDe commented 4 years ago

I threw an unnecessary amount of time into subdomain auth recently. I have a subdomain that sets cookies, and auth should use those cookies on the root domain. Seemed simple enough, but I just couldn't get it to work. After going through the source, I finally found that you can give individual endpoints in the Auth module withCredentials: true. That did it.

withCredentials: true is in general important to know about when working with cookie auth etc... Perhaps mentioning it more would be good, and that it's set to true by default on some auth providers, which was what tripped me up partially, since it seemed to work out of the box when I started for one auth, then broke for one I created myself.

codeofsumit commented 4 years ago

Nuxt improves a lot 😍. At this time, I would also vote for the auth module to be the most in need of a documentation overhaul. A lot of guesswork and looking in the code happens to make it work with main providers like auth0. Looking forward to v5 tho

andrewmackie commented 4 years ago

Thanks for NuxtJS.

The docs on dynamic routing are confusing.

To make dynamic routing work in SPA mode with nuxt generate, you must set generate: {fallback: true} in nuxt.config.js. This should appear as a note under the 'Unknown Dynamic Nested Routes' section. Because it's not there, people will likely go down the rabbit hole of attempting to extend the router by following the instructions in the next section (as I did).

Instead, generate: {fallback: true} is mentioned further down the page under 'SPA Fallback', where it's described (misleadingly) as a setting related only to 404s.

I would do a pull request to change it but I'm not sure how SPA Fallback section should be rewritten to make it clearer, sorry.

debs-obrien commented 4 years ago

Thanks so much for the feedback. @VesterDe, @codeofsumit it's next on the list so we will be improving that sorry for having to do all the guesswork lets hope our improvements makes things easier for you and everyone else. @andrewmackie yes I know, we have actually spent the last 3 months revamping our docs and they are just about to be released. as soon as they are then if things are not fully explained a pr or feedback would be great. Thanks for taking the time and hope you continue to enjoy using Nuxt.js 💚

HappyColour commented 4 years ago

Hello Nuxt Team . I'm using the NuxtJs build my company website：https://www.niu.com/ . I think the website performance is good, because i have optimized it. However, when i open the google pagespeed insights：https://developers.google.com/speed/pagespeed/insights/?url=https%3A%2F%2Fwww.niu.com%2F Wow, the score is too low on mobile especially . I have tried too many ways but no effect . So, I hope you could help everyone like me . Thx Nuxt.js Team .

debs-obrien commented 4 years ago

Thanks for your contributions. We are now closing this repo as docs have now moved to nuxtjs.org using content module. Please continue your contributions on that site especially focusing on the guides folder which is the new docs. Thanks

https://github.com/nuxt/nuxtjs.org/blob/master/README.md

nuxt / docs