gajus / gajus/isomorphic-webpack

Improve documentation

Open
#26 2 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
JavaScript
Stars
289
Forks
16
PR merge metrics
No merged PRs in 30d

Description

Hey Gajus!

Thank you for this module! Looks like you have really explored the bowels of webpack and have put together something very useful for setting up isomorphic apps.

I finally managed to get this to work and would like to let you know about some of the issues I found while attempting to use this.

Following here are a few things that stumped me and caused me to waste time setting this up:
___
#### You must use resolved absolute paths to your entry points within entry points.
I had been using relative paths to context which is quite valid for webpack-dev-middleware to serve.

#### You must use arrays to wrap your entry point paths
Again this is not being as flexible as webpack if this is a requirement it would be great to have some kind of reminder or documentation

#### You can't use a fancy libraryTarget setting
Entry point `output.libraryTarget` must be set to the default (which I think is `"var"`) or at least certainly not `"umd"` like I had it set to from the config I was branching off.

#### No example for a production build
I know this is only meant to be to enable a dev server but in reading the readme it takes a while to actually grok the usecase.

It would make it quicker to understand and implement if there was a build script included in the demo. I understand that this would have nothing to do with the library and that you want to present a minimal example to focus on how to use the lib but honestly a bit of context would really help out someone with new eyes to the space. Perhaps you could provide a couple of examples?

Personally I knew didn't want to use this in production to serve my routes as it is poor practice however this gets integrated a little deeply when you try to create a real project and setting it up is kind of involved and without an example of a build step I couldn't tell 100% if you were actually using this in production. Anyway a `build` script would help remove the confusion.

___

Now I was not sure how you wanted to present these things in docs but wanted to document somewhere for other users that are trying to get started with this which is why I opened this issue.

Again thank you very much and great work!

Rudi

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the README and the demo referenced in the issue, focusing on entry-point paths, array requirements, libraryTarget settings, and production use. Done means the documentation explains these constraints and includes or describes a production build example clearly enough for a new user to understand the setup.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.