VuePress: a fully Vue-powered static site generator | Hacker News Reader

VuePress: a fully Vue-powered static site generator

vuepress.vuejs.org

187 pointsconnor11528119 comments

First, I'd like to say I'm a big fan of Vue.js. I've used it for a few production apps.

> Enjoy the dev experience of Vue + webpack

I just find this confusing. The only reason I tolerate webpack is because of how convoluted the front end web build chain has become.

I honestly think you must be a sadist to use something like this. It sounds like it might get around the SEO problems SPAs suffer from somehow, but seriously, just use Hugo or Jekyll!

Seriously, I have been writing code for almost 30 years now. I pick up new languages and packages and love hacking on new things still. Modern front end developmemt feels so bad in some areas. I spent full /days/ trying to tame webpack and friends and just gave up. "Modern" web front end developer is a weird and annoying place. I would rather battle pthreads and kernel bugs with gdb than try to figure out web front end. There are some bright spots. Vue is nice enough. Bootstrap has always made sense. jQuery is easy enough. But man, I remember IE4 vs NS navigator compatibility being more pleasant to manage in some ways to learning some of these JS frameworks. And I am not just expressing a grumpy get off my lawn sentiment. This stuff is legitimately obtuse. But in a strange way compared to say systems programming. Systems program is deep and sort of orderly. Modern JS is broad, chaotic, frustrating.

I think what's started to happen is there is an entire generation of new coders that grew up on Javascript and the web and so all of this just seems totally normal. I look at some of this static site and server side rendered Javascript stuff and wonder if the people developing them have ever used flask, or Sinatra. I mean hell these frameworks make RoR look lean and simple.

Yes we have, and while the various new JS frameworks may be a bit more complicated they are also vastly more productive environments. For example webpack's development server let you develop your app with real time updates with hot reload. The productivity benefits from just that are worth more than a few days of setting up webpack. And that's just one thing webpack provides

I dislike hot reload for a few reasons. One, it makes it difficult to keep two tabs open to compare the "before" and "after" of a change, because both tabs reload the "after" instantly. Two, you can get into an "impossible" state where you've navigated into a section of the site and get to see an "after" state that turns out to be unreachable because the change affected earlier navigation. Three, it is often unclear if everything reloaded properly during a hot reload, especially if you have also fiddled around with stylesheets etc in the chrome developer console. To each his own, though! :)

How is the productivity benefits from not having to press F5 after I'm updating the code is worth a few days of setting up Webpack? If I sum the time it took me to refresh pages since I started using the internet it doesn't get to a few days.

> How is the productivity benefits from not having to press F5 after I'm updating the code is worth a few days of setting up Webpack?

It doesn't take a few days, it's more like a few hours, and it's completely worth it. It makes development much less frustrating, it reduces cognitive load (no switching back and fourth between windows) and it's faster (includes not having to get the app back into the state it was in before with hot reloading).

When compiling and reloading is something you're doing hundreds of times a week, a seemingly small improvement makes a huge difference to how enjoyable it is to work on a codebase which makes you more productive. I'd say the same thing about reducing a test suite run from 10 seconds to 1 second; it might only be saving you a few seconds each time but it makes you more productive because tightening the feedback loop reduces frustration which increases productivity.

There's nothing worse than attempting a fix, waiting 60 seconds in anticipation it worked, seeing the same error message as last time and then having to try again for instance.

Besides that, you don't even have to set up Webpack yourself if you're using the vue-cli app to create your boilerplate.

I've never set up Webpack myself, but I'm getting all the benefits.

Unless you have you entire state stored persistently across refreshes, then hot loading takes care of getting into the exact state you were in again. Make a small change -> immediately visible in the UI. Before hot reloading, make small changes -> (automatically) refresh page -> navigate to where you were, and set up the state again you were in.

Hot reloading saves so much time, and means you'll check for smaller increments, because it's painless.

You're not counting the fact that a refresh may require developers to get back to the app state right before refresh.

Yeah, maybe. But I'm also not counting the times I worked on a hot reload enabled project and I wasn't sure if it actually reloaded or maybe there was an error somewhere that made the whole thing stop working, and so I just manually refreshed. It's just not that amazing, and it certainly not worth a few days of setting up. Would someone really start a project from scratch and then spend days on getting hot reload to work? I'd never want to hire that person honestly, nor to develop in such a fragile platform.

Hot reload is nice, but there's nothing revolutionary about it that justifies more than an hour of getting things to work.

Oh no I agree. It's far more painful than it needs to be.

I've found productivity boosts in shortening the feedback loop. A tighter feedback loop makes it easier to get into flow.

But days of effort to get a simple thing working defeats the purpose. My worst days are when I look over the day and I've spent it fixing a build process - there's no flow in that. I could just bite the bullet and still get into flow albeit less smoothly but still. That's how I worked for years.

I just wanted to point out it isn't as simple as eliminating a refresh. There is a gain behind that.

Plus, it uses a lot of CPU/battery everytime you save in your IDE whether you're going to actually check the result or not.

If either of those are actually problems for you then your dev environment leaves a lot to be desired.

You can't be wasting cognitive load on that.

Webpack takes zero time to setup if you use any of the popular boilerplates or standard generators.

This actually sounds hyperbolic to me. Are you sure that's the case?

I'm not sure. But since the average time for a webpage to load is about 3 seconds[0], I would need to press F5 17,280 times to be refreshing for a whole day. I don't think I have, and even I did, quite a few of these had nothing to do with me developing anything, so hot-reload wouldn't help here.

[0] https://www.semrush.com/blog/how-fast-is-fast-enough-page-lo...

It's probably completely hyperbolic. No way it should take days unless you're trying to retrofit a legacy project and learn it at the same time.

Eh ... right this moment, I'm watching Firefox auto-reload the stuff I'm working on, by the sheer magic of me saving files in my editor. This is pug, scss, assorted js, svg, you name it. Am I missing out on man-years of productivity for never really having taken to the brontosaurus model?

Nah, I think the trend of the commentary was just that the tooling is hard to learn how to set up. I think it is probably worth setting up and learning the tooling if frontend work is a non trivial part of your life. But as someone who just wants to put a toe in and feel productive it can be rough to find easy to use front end frameworks.

Haven't we had auto reload since long before webpack? Or am I missing something.

Real time updates and hot reload are almost completely independent of js and webpack. E.g. Middleman has that via the ‘livereload’ feature.

Hot Reload is not unique to webpack. Hugo for example, provides hot reload. At the same time it's an insanely fast static site generator, which you install by simply downloading a binary. No tools, no dependencies, no hundreds of thousands of node modules.

Hot reload is not unique to webpack. The multi-day setup or the multi-day attempts to set it up followed by giving up, are.

I very much would like to use a simple, sturdy, predictable environment and trying to work with webpack has brought me only frustration.

Things that should get chained together and just work, don’t. To fix them I needed to understand obscure bugs in infinite npm dependencies. I’m not that good at JavaScript and honestly don’t want to be.

I would gladly pay $50-100 per set up if this service existed.

> The only reason I tolerate webpack is because of how convoluted the front end web build chain has become.

I've moved back to browserify (/ watchify) for hobby web projects and I've been very happy with it. Its a huge relief to jettison all the complexity that webpack brings. Browserify configuration often fits on the command line even for complicated projects. You have great tools for analysing bundle size with disc[1], and you can do hot reloading on SPAs with budo[2]. The ecosystem has babelify for JSX, tsify for typescript, uglifyify + unassertify for minification, and sheetify for CSS.

Browserify also seems way faster. I haven't tried webpack 4, but with webpack 3 I've had plenty of builds that take nearly a minute. Its out of control.

Webpack seems like the web generation's automake & autoconf. How long before we have tools which generate webpack configuration programatically, and which need configuration themselves.

[1] https://www.npmjs.com/package/disc [2] https://www.npmjs.com/package/budo

I recently made the switch to using ParcelJS [1]. Came from a browserify + rework + npm run scripts setup and wanted something with 0 configuration for my projects. Parcel's been that for me.

Disclaimer: I'm not a serious webapp developer/software engineer. I mostly build websites so mileage may vary.

[1] https://parceljs.org/

Webpack 4.0 also has zero config and it works exceptionally well.

> How long before we have tools which generate webpack configuration programatically, and which need configuration themselves.

Haha, too late! I actually really enjoy using Laravel Mix, which despite the name is not tied to Laravel. It's a Webpack wrapper that simplifies it significantly for many common use cases.

https://github.com/JeffreyWay/laravel-mix

Mix is great! Webpack is very powerful and complex, but 90% of the time I just need to compile CSS/Sass and ES6 Modules. For these common scenarios, Mix makes this super-simple without having to dig into the Webpack config. If you stick with the very sensible defaults, your config can be as simple as:

mix.js('resources/assets/js/app.js', 'public/js') .sass('resources/assets/sass/app.scss', 'public/css');

Here are the docs: https://laravel.com/docs/5.6/mix

Glad you are enjoying budo! It's a little tool that I built before Webpack became so popular, yet I'm still finding myself using it daily for the last couple years.

I'm actually working on some new tools that combines my favourite parts of budo, webpack, babebl, and parcel... But ultimately with very similar usage and "unix philosophy" approach as the rest of browserify. :)

I also feel like browserify resonates better with me.

I use the browserify plugin "tinyify" to make the final output smaller: https://github.com/browserify/tinyify

If I'm working on a choo app I use banaki which uses browserify and my preferred bundle optimization plugins/transforms under the hood: https://github.com/choojs/bankai

Even better than watchify is the combo entr + browserify-incremental.

I understand your frustration. I had the same problem as you: I found webpack waaaay too abstract. Tons of configuration was needed to even begin and there was little to no documentation that I could follow as a mere mortal developer.

So what I did was to rewrite the majority of their beginner guides by submitting PR's for 2 reasons. 1: help out people like you and me. 2: learn about webpack in the process.

I can really recommend following along with the Guides, because they use really, really basic examples and become more and more "complex" (it really isn't) as you follow along.

You can find the guides here: https://webpack.js.org/guides/ and I really hope it will help you.

It isn't as difficult as it has always seemed and if you have any struggles: don't hesitate to give the webpack team (including myself) feedback so we can improve the docs and guides.

Hope it helps!

> but seriously, just use Hugo or Jekyll!

Both of those lack support for custom "sources", instead of just markdown files.

A lot of people like Contentful (https://www.contentful.com/), which static site generators like Gatsby support.

This doesn't really address your remark about webpack though.

However, I have been using Gatsby and I haven't had any issues with it. It is completely internal and hidden from the end user.

> Both of those lack support for custom "sources", instead of just markdown files.

For me that's the beauty of it, just simple structured text files. If custom sources are needed for a static website then writing a transform script to generate the markdown files and yaml header is simpler than having to deal with integration apis.

> Both of those lack support for custom "sources", instead of just markdown files.

That's why I wrote sitio[1]. sitio has a pretty simple imperative API where you can say stuff like "generate page on /about/ using the React component on 'components/page.js' and the following data: {}", so your entire configuration is just a simple nodejs script and you can use data from anywhere.

Then it generates static pages that, if JavaScript is avalaible, will become React components and the entire site will be a Spa with proper history. If there's no JS, it's an HTML static site.

Also, it uses Browserify under the hood, because Webpack is horrible.

[1]: https://github.com/fiatjaf/sitio

Interesting project!

Does it generate pure html, without react support?

Yes, it does. Actually if you don't include the main bundle.js you'll be left with just HTML and everything will be great.

What do you mean by "custom sources"? Hugo can load JSON from external APIs during build: https://gohugo.io/templates/data-templates/

No support for slim is a dealbreaker for me. Once I tried slim I just can’t force myself to write and read html.

Middleman / Jekyll both support slim, webpack if needed, live reload, json or yaml data files, partials, page matter (in-page data in yaml format) etc.

The only issue is setting up webpack (for vie and Babel in the middleman specific confit).

Oh yeah, forgot about that.

Also, Hugo lacks support for plugins. If you want to do something with it, it better be baked-in out-of-the-box.

https://github.com/middleman/middleman may also be an option

Ugh. A colleague was struggling with a webpack set up. He was waiting like 30 minutes to rebuild a CSS change. Meanwhile, I'm using Sass on 2 projects, with around 100ms build times inc. live reload. Clearly there's reason for the disparity.

So we looked and it turns out the webpack fast-sass-loader was around 3000% slower than just sass-loader. It now takes 3 seconds to build CSS changes. That to me is still too high for CSS but it's an improvement.

There seems to be a heavy overhead with webpack in terms of both configuration and actual performance. We may have configured it wrong or maybe fast-sass-loader just isn't as advertised.

Between that and package.json containing a makefile on top of dependencies, it's all a bit nuts.

> I honestly think you must be a sadist to use something like this.

A nitpick, but this says something a bit like the opposite of what you intended. You mean "masochist".

maybe a sadomasochist

What indication is there of the "sado" part? Using webpack doesn't inflict pain on others, does it? (I've never actually used it myself, but the OP only seemed to imply hurting themselves with it.)

Hearing about it is pretty excruciating.

Does not have to inflict pain on others.

Sadomasochism is the giving or receiving pleasure from inflicting or receiving pain.

With that being said some people like seeing their team suffer. No sense of accomplishment if there was no struggle.

What about your team?

fair enough

Not sure why this is the primary concern but... did you even try it? Webpack is really an internal implementation detail for VuePress and not visible at all in most use cases.

Eh, Webpack is not so bad. The problem is using tools like Vue CLI which have overly convoluted configurations. If you make your own it will fit your needs and you can reuse it on every project.

Parcel is a lot simpler but it still isn't ready for prime time (with Vue at least).

As for static sites I agree. Simpler solutions like Jekyll, Gitbook, etc, make a lot more sense.

Wasn't Vue CLI's config pretty much all webpack? (BTW they are moving into a zero-config approach with v3)

Vue CLI 2 is also a zero config approach (if you are ok with whatever template you are using). The big thing in v3 is that it's based on plugins.

So, not so much zero config as prefab config :)

Webpack is not hard, the config is a simple javascript app that has to return an object following a specific schema. It's a list of entries (the starting file of an app) and the loaders to use for each type of file, based on a regex test of the filename.

It is maybe 0.05% of the difficulty of any actual app. Why is it so confusing when you can clearly create real apps without a problem?

> Webpack is not hard, the config is a simple javascript app that has to return an object following a specific schema

There's so many variations in what stacks people are using and what build steps are required for different projects that setup issues and bugs to workaround are virtually inevitable.

I want to move up to the next major version of Webpack for one project for example but after spending a total of several days getting my builds working correctly already, I'm almost certain it'll eat up at least a few days to get everything working again (e.g. production and development builds, source maps, live reloads, hot reloading, template compilation, TypeScript compilation, SASS compilation, project paths, optimizations).

Saying it's just simple JavaScript is completely overlooking all the plugins and configuration you have to stitch together and when things go wrong it can be challenging to know what to Google for.

I understand, but that's more of an issue of there being so many external plugins. The entirety of webpack itself is just a small core runner with plugins and they're slowly moving more functionality into the main package.

Fundamentally I think the issue just comes down to terrible documentation and the spread of outdated blogs and examples as a result. The team seems to know that and they're working on it but it should be the highest priority for them.

Honestly though, starting from scratch, you can build a complex config (with all those things you mentioned) in about 30 minutes. If you really need help then post it here or on stackoverflow and you'll get an answer pretty quick.

> Honestly though, starting from scratch, you can build a complex config (with all those things you mentioned) in about 30 minutes.

If you're sticking to a pre-built template or simple defaults maybe but once you start to customise things it's easy to get stuck in your own unique problems. Resolving path issues can easily eat up 30 minutes alone so I'd say you're severely underestimating.

> If you really need help then post it here or on stackoverflow and you'll get an answer pretty quick.

Once you've got your own unique combination of plugins going, it gets difficult to know where the problem is and you're less likely to get help if you've got something bigger than a minimal example. I know how to ask for help but there's just something about build system which makes it more challenging and more frustrating to get help compared e.g. typical programming problems.

I'm not sure why paths are such a big issue. The config object only needs the path to your applications entry file, and the path to where to put the output. All the paths within your app js (the import() statements) dont have anything to do with webpack and wouldn't run anyway if they were wrong.

What other paths are you running into problems with? Also debugging this is just like any other app, start with 1 line at a time and see what changes. You can technically run it all inside of a debugger but that's a lot of setup so the old-school 1 change at a time + console.log() statements work well. Remember its just a single-file js app that produces an object.

The issue is that for the result there are too many variables and unknowns that complicate the most important thing. Writing the app and not taming the build process. Take Ember for example. It lacks the freedom to configure as you please but gets you going creating very fast.

It is with the paths in your styling (images, fonts) which by default are checked and rewritten during compilation (which fails if he can't find the files).

I feel your pain. Tried moving away from bower + simple gulp concat to pure NPM and webpack on an old angular 1.x app. Ouch.

Webpack as of now reserved to just vendor. Porting the whole app over will take a significant amount of work. I don't have that at the moment, not with 2 or 3 deadlines on my plate!

The webpack "schema" is extremely complex and dynamic in shape. You can often return a scalar, or an Array, or some objects with various optional keys for the same config option. That choice has a cognitive price and documentation fails to document all this in a sane maner.

Also, even the most popular webpack plugins have trouble tracking the latest version of webpack and you often still have blocker bugs months after a release, so you often have to try many, many combinations before your workflow does what you want.

Right, so it's not difficult but just annoyingly undocumented and unfinished. I've already stated that it's the biggest issue with the project and something they should resolve before making even a minor update, but the lack of any project managers makes that unlikely.

Webpack allows writing the config in typescript so you at least have static analysis on the correctness of the config object you generate.

It’s a huge pain when a new version of webpack is released and most existing guides become outdated.

Yes, documentation is the single biggest problem for the webpack team and something they seriously screwed up with the release of webpack 4. I think they understand now but it remains to be seen. Unfortunately they have lots of devs but no clear project manager, which is what really makes larger projects work well.

The step from 2 to 3 wasn‘t great too though.

It is by far the least intuitive configuration I ever regularly encounter.

That's because it's not a config file, it's a javascript app that is run to produce a javascript object, which is then used as the config.

That object needs 4 main properties: the entry (the file where your app begins), the output (where to put the compiled stuff), the loaders (what to use to load various file types identified by a regex to test the file name), and plugins (for anything else that operates on the compiled output).

Gulp was JavaScript as well, and much simpler to understand!

>SPAs

Single page applications?

Yes, from the front page:

> VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.

Today I learned. Thanks very much!

The latest version of the vue-cli (might still be in alpha or beta) generates an app where webpack works out of the box very nicely

Or Wordpress :)

It's not bad once it's set up. For example, hot reloading your application state.

Webpack is basically zero configuration now - with v4 - so I’ve no idea what you’re doing to make it impact your life so.

It literally is one command running in the background

It's zero config as long as you follow its conventions.

...using JavaScript?

I mean as long as you use import or require it just works. Everything else is optional.

You can use all that other stuff but there’s zero requirement to do so.

What conventions do you mean?

For example that the entry point has to be ./src/index.js

It doesn't have to be. Mine is ./src/client.js for example

If you want zero config then there are assumptions it makes, but that's true of all zero config setups - they assume defaults.

Changing it is one property in a config file. Not exactly tricky or complex.

I'm a big fan of Vue.js over React because of how much smaller and simpler it is. VuePress looks interesting. Is this seen as a competitor to GatsbyJS, or is it more focused on only docs sites?

Do you have experience with React? React is really simple, and I think Vue looks simple on the surface but quickly turns into Angular level of mess.

Yeah, I've worked on medium-sized apps with React (mostly 1-2 years ago) and small to medium side projects with Vue. The number of components and rapid shifting in the React ecosystem, not to mention the absurd number of dependencies installed by create-react-app were some of the major sticking points. It all got pretty messy eventually. That experience with React is what led me to Vue personally and got me to appreciate it.

Vue.js looks more limited on paper but it was the "React Lite" that removed all of the options that ended up being used to make for complex codebases that made it work for me. It's worth noting that my React experience was with others on a dev team while Vue was solo.

Can you talk about why you think Vue turns into a mess, especially why you think it is worse in this regard than React? That runs counter to my experience, so I'd be interested n understanding your experience.

I have experience with both. I find Vue much easier to use and am way more productive with it.

React also tends to turn into a mess quickly... not saying vue or angular are any better, it’s just js ui code is a awful mess in comparison to even 20 year old desktop ui frameworks.

How much experience do you have building Vue apps?

Do you have experience with Vue?

There are lots of reasons to use Vue because it's awesome, but if your main concern is size then Preact is about 20% the size of Vue.js 2.

Even though Evan You addresses how this measures up to Nuxt, unless you absolutely need Markdown out of the box, I find Nuxt already has Vue’s static site generator crown. Just run `npm run generate` to get a static site you can host on S3, Now, Nearly Free Speech or wherever you prefer to host static files.

If Nuxt added support for Markdown out of the box it'd be perfect I think...

At least, would cover any Jekyll or Hugo users' needs.

Another one to add to the list of static site generators: https://www.staticgen.com/

Question: what is the advantage of SPA for a statically generated site?

Once the first page is loaded subsequent interactions that would normally require a full page request can be done with smaller requests and with nice transition effects.

Lately I've been thinking that browsers could do whole DOM diffing for the transitions between the same origin.

Browser could just retain a current DOM, then just replace what's different.

I wonder how hard would it be to implement.

I understand that it's not how it works currently. But I hate that most SPAs out there fail to signify progress and failure. I click something and nothing happens. It's infuriating.

Something like https://github.com/turbolinks/turbolinks ?

Yes, but built-in in browser.

Edit: and fully automatic. Browser would try to replace what it could, but only as long as the origin remains the same.

For all those who are unhappy with WebPack, I seriously recommend brunch (http://www.brunch.io). It used to be the default that ships with Phoenix/Elixir (not sure if it still does) and it's really straightforward to get started with it.

For our app, we use Jekyll+Brunch for the static site with about, contact us, etc. And Phoenix for everything else. Brunch + VueJS is a breeze (unless you're into dynamic imports, which is required for SPAs).

I dislike Webpack and tried using Brunch with a Phoenix+Vue project but it failed short when importing npm modules in my Vue components (another Vue component, a lodash function etc).

It's sush a basic functionality that I was sure the problem was my code but no, it's a ongoing problem with Brunch [1][2].

I like the concepts in Brunch but the project seems to be short on manpower (look at the dates on the issues and PR), and vue-brunch is kinda unmaintained as well [3].

I think Phoenix should move to Webpack or at least support more bundlers.

[1] https://github.com/brunch/brunch/issues/1553 [2] https://github.com/brunch/brunch/pull/1664 [3] https://github.com/nblackburn/vue-brunch/issues/22

I've started using brunch.js in my side project (HTML5game). the only bad thing I've noticed is problem with importing modules - I need to save file 2 times because when I do it only once then the imports will fail to load - anyone experienced similar bug?

How is Brunch with importing fonts and SVGs these days?

They are changing it to Webpack 4.0 :D

Why use this instead of something like Jekyll?

Because you get first class support for modern JavaScript while staying true to being a static site first.

But isn't the point of making a static (.md or html based) site not having to deal with JavaScript in the first place?

No it's the opposite, static websites are just static files, they work without requiring backends. JavaScript on the front-end is usually static files, but this enables first class support for modern JavaScript while losing nothing else about static websites.

Usually the term "static site" is regarding no backend language ie PHP, Node, Ruby serving posts out of a database dynamically, but instead being prerendered rather than not having any JS on the front end.p

I have used vuejs for about a year now, my primary development is in django and vuejs is a tool for writing SPA like calendars and IOT dashboard components, all said I think what you are out to achieve is a great idea and I am certainly going to give it a spin, thanks

Where is the demo?

The site is literally a demo

I have spent the last 2 hours trying to work out if there was an alternative to vue-markdown for Nuxt. 500kb to parse my markdown seemed insane.

Does vue-markdown not work with Nuxt?

I use marked.js on my own site. Works fine on NodeJS or in the browser.

It does. Monterail has a Nuxt repo for hackathon type sites and some pages used a Vue based markdown component.

I’m trying to build a static site with content coming from Contentful. I don’t want site visitors to have to download 500k of vue-markdown before they can see the content. Am I missing something? Is there a better way?

But the final site is static right? Because a Nuxt site even works with JS disabled?

It’s a static site (as in it doesn’t need a web server) but vue-markdown to HTML conversion still happens in JS on the browser - so the browser needs a 500kb supporting JS file. If JavaScript is disabled then you won’t see the content.

Reply on news.ycombinator.com