arecvlohe commented 7 years ago

In talking with @TheLarkInn the other night I proposed the idea of creating minimal quick setup guides for all frameworks. I mostly work with React so that is where I would start. The quick setup guides would consist of a folder structure, necessary npm modules, a minimal webpack configuration, and a recommended command in package.json. Below is an example of a quick setup guide for React.

Quick Setup Guide React

This guide is intended to show you how to quickly get setup with React application using a minimal webpack configuration. First, let's setup our package.json so that we can pull in any necessary npm modules. Navigate to your project directory in your terminal and then type:

npm init -y

This will create a package.json file with all the default values already set. You will need a few npm modules to in order to use some of the latest features of JavaScript and React. From your command line type:

npm i -S react react-dom && npm i -D webpack webpack-dev-server babel-core babel-loader babel-preset-env babel-preset-react

Next, let's establish the folder structure. The folder structure for this React application will be:

dist/
  index.html
src/
  index.js
package.json
webpack.config.js

Now let's configure your webpack.config.js. At the very basic level you will need an entry point for your application and a output. You will also need babel to transpile your code into ES5. A minimal webpack configuration would look something like this:

const path = require("path")

module.exports = {
  entry: path.resolve(__dirname, "src", "index.js"),
  output: {
    filename: "bundle.js",
    path: path.resolve(__dirname, "dist")
  },
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: "babel-loader",
          options: { presets: ["env", "react"] }
        }
      }
    ]
  },
  devServer: {
    contentBase: "./dist",
    historyApiFallback: true,
    stats: "minimal"
  }
}

After this we can almost begin coding. Inside of your index.html we need to setup some basic html and a div that we can mount our React application. In your index.html type:

<!DOCTYPE html>
<html lang="en">

  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Quick Setup Guide</title>
  </head>

  <body>
    <div id="root"></div>
    <script src="bundle.js"></script>
  </body>

</html>

In our index.js we can start to setup our application. You will need React and ReactDOM to render your application and mount it to the root div in your index.html file.

import React from 'react'
import { render } from 'react-dom'

const root = document.querySelector('#root')

const App = () => <div>Quick setup guide</div>

render(<App />, root)

To run the application we will create a simple command in your package.json to kick the whole build process off. Under scripts you can put this new command:

"scripts":  {
   "dev": "webpack-dev-server --progress"
}

Afterwards from your command line run:

npm run dev

Navigate in your browser to locahost:8080 and you should see Quick setup guide in the body of the html document. Any changes made in the index.js will automatically recompile your project and you will see the changes in your browser. Happy webpacking!

So that is the gist of it. Please provide any feedback as to the value of such an addition to the webpack documentation.

TheLarkInn commented 7 years ago

I really like this idea and really opens the gates for lots of fw experts to chime in, could you imagine this as a subsection of /guides/

(Some info arch should be done to ensure that wherever we add this, that we do so in a place that's easy and accessible) cc @skipjack

mrmartineau commented 7 years ago

@arecvlohe, @TheLarkInn mentioned this thread on Gitter just now. I recently created a new repo with common recipes for different webpack configs. It is unfinished and needs improving but I think it might become an invaluable resource for webpack devs: https://github.com/mrmartineau/webpack-recipes

Would love to hear your thoughts.

TheLarkInn commented 7 years ago

Here is my two cents:

People's primary use cases are:

Use webpack with xyz lib/fw.
Learn how to use style, html, etc. other features integrations w/ those libs/fw's etc.

So I think there's a good opportunity to take the the content like @mrmartineau and provide it in a case by case, and supplimental to part-1 basis.

arecvlohe commented 7 years ago

Yes, I had the same idea. How to create a general setup with React, then React w/React-Router, so on and so forth so long as webpack is integral to the general setup. Then we can have one-offs that work for any setup and whose configuration remains relatively the same, like for CSS modules for example.

arecvlohe commented 7 years ago

@mrmartineau It looks like we are on the same page. I am somewhat familiar with Elm and JS so I think I would be able to create a React, Elm, Choo, CycleJS, Elm setups relatively quickly. This is kind of nice too since people may want to try out these different frameworks but just want to get something up and going as a proof of concept and not be bogged down with configuration or spend time figuring out best practices.

arecvlohe commented 7 years ago

I think were I have had the most issues are with code splitting with React, RRv4, and HMR. I have seen a bunch of blogs but found I was running into some dead ends trying to get them all working together. Some setups I saw were crazy complicated, at least in my view, so I didn't want to use it without really understanding how it works. Another good example but one that is a bit more complicated is getting webpack-middleware working with a Node backend so that you have webpack and the api/server working in the same port. I was able to get something working and I think it this type of example would be helpful to others. I guess it would be called full stack React/Node webpack setup or something.

mrmartineau commented 7 years ago

@arecvlohe I had actually never thought about providing recipes for framework/library-based configs but I can see how it would be useful. I am keen to help and improve this resource in whatever way possible. Let me know how you'd like to proceed.

skipjack commented 7 years ago

This is something that we've @bebraw and I have discussed with others a few times -- and previously some framework-specific discussion slipped into the current and previous guides. While I understand that it sounds like good idea, I feel pretty strongly about not including these, or at least not within this site, for the following reasons:

This increases the scope of the docs significantly just content-wise (all frameworks is a lot and we can't be biased towards one or another)
Other frameworks and libraries API's can change -- i.e. not only when webpack releases changes does the site need to be updated but also when any of these other frameworks change
webpack is a complex tool by itself and there's a ton of work just to get the existing docs in good shape, so I think this sidetracks us from the main goal
There are a lot of frameworks out there, so, while it may not seem like much with the most popular ones in mind, who draws the line of what's included and what's not? I think if we start adding framework-specific guides it makes it seem as though we're recommending certain ones over others when webpack is really a framework agnostic tool.

I think a better solution is to write these as separate blog posts and then link to those within the core guides that they relate to. That way, we're not directly responsible for the content and it's easy for any up-and-coming frameworks to add links without us having to review and maintain everything. Sorry to rain on the parade 😞, but just speaking as maintainer of this repo, I really think we should think hard before digging into this as it's hard to step back out (i.e. people don't react well to content being removed or features taken away).

mrmartineau commented 7 years ago

@skipjack FWIW, I am going to continue updating my repo, so if that's the only place it exists, then so be it. In my opinion, blog posts aren't the right place for this kind of information because I find that they can't be relied upon and go stale quickly. With a repo, you can see when everything has been updated etc.

skipjack commented 7 years ago

@mrmartineau yeah I actually like your repo idea too, definitely could work better than a blog post -- that's something we can link to within our guides as well. We may actually have some kind of follow along repo to go along with our guides at some point. Didn't mean to say blog posts were the only way, my main point is that it should be externalized for the reasons I listed above.

We already have sections in some of our guides that link out to other framework-specific examples, usually with some encouragement for people to add to the list. We could even make this a bit more official by including it in the YAML front matter and handling it consistently for every page.

arecvlohe commented 7 years ago

Yeah, I think I will work on a repo as well to show how to do basic setups with webpack. IMHO without having such basic examples in the webpack docs, I think using webpack will continue to be a frustrating experience for many users, especially those just starting out.

skipjack commented 7 years ago

@arecvlohe you think having them in the site vs. linked to really makes that big of a difference? For an example see the bottom of the HMR guide. Another external example aside from the ones linked there is this react-specific code splitting guide that we should probably link to from Code Splitting or Lazy Loading.

Look, at the end of the day though, it's not just up to me. If the @webpack/core-team feels strongly about moving forward with this, I won't stand in the way. I just really think that it spirals out of control very quickly, evidence of which we've already seen and is one of the reasons for #1258. @bebraw what do you think, am I overreacting here?

arecvlohe commented 7 years ago

@skipjack I don't think you are overreacting, I just think we are coming from two different perspectives. You, rightfully, want to focus on more on the greater goal. I am more focused on reducing the barrier of entry to getting started with webpack for new users. We can agree to disagree on how to achieve that and that's fine too.

And from my perspective, the guides that are referenced don't easily point to setting up a simple project. I tried using those guides myself and found that I had to dig through a few github issue threads to find the solution. So from my perspective it does make a difference.

I am certainly not going to push this issue if the team feels strongly against it. At the same time I did want to share my thoughts and try to share the perspective of how some beginners might feel because if it's that difficult for me, I can only imagine what they might be going through.

TheDutchCoder commented 7 years ago

If I may chime in here :)

I'm currently working on rewriting some of the "beginners" guides and at the same time I'm working on a repo of examples that go with the guides as "starting points" and to help people learn how webpack works.

I think the proposal @arecvlohe made is very much in line with this approach as well.

A lot of people will get familiar with webpack through a fw, like React, so in my opinion it's worth including examples for a couple of frameworks.

My suggestion would be to put those under their own section in the Guides. We were already debating about splitting the Guides into "Beginner" and "Advanced" sections.

For me this would fall under "Advanced" (as I think "Beginner" should really touch on the basics and fundamentals, whereas using webpack with a fw is usually already quite a bit more complicated).

How about we create a section for this under "Advanced" guides @skipjack ?

skipjack commented 7 years ago

@arecvlohe so did you struggle with the latest Getting Started guide (after @TheDutchCoder and I revised it)? It seems like you're mainly referring to having variations of Getting Started that guide. Currently there are no reference links to framework specific setups there but we could easily add a section that links to repos/articles that do.

@TheDutchCoder there's a big difference between "All Frameworks" and a "couple of frameworks"... also it's one thing if we do this and strictly limit it to Getting Started instead of including framework specific instructions for all guides. My only worry there is that once it's in Getting Started, we'll get a lot of framework-specific asks for all the other guides.

Re placement within guides, I don't think "Advanced" really makes sense if it's just going to be variations on Getting Started. I guess if we were to do it maybe a Common Frameworks section or something.

Idk I guess imo, I just think that for most people if they can get a basic setup in place, they won't need to much more instruction to pick things up. Really all you need to do to start using react in the Getting Started project is:

npm install --save react react-dom

and then start using it in your src/index.js file like @arecvlohe showed above:

import React from 'react'
import { render } from 'react-dom'

const root = document.querySelector('#root')

const App = () => <div>Quick setup guide</div>

render(<App />, root)

Edit: To be fair I guess I am leaving the babel / babel-loader config out here although you can write react modules without JSX...

Maybe just a small section stating that webpack is framework agnostic and showing a quick example in one framework like react?

arecvlohe commented 7 years ago

@skipjack I think I would have struggled more had I not found a good resource to create a basic setup. As you mentioned, I remember there was a doc on getting setup with React and then a few months later it was gone. That was really helpful and at the time I thought it was strange that it was taken out. I then had to keep referencing http://www.pro-react.com/materials/appendixA/ just to get a project started. Pro React has been just as valuable as any documentation on webpack because it shows me how to use it, not just what it does. Now that I have done a few projects under my belt I feel more comfortable but it took a while to get there.

I think a Common Frameworks section makes sense.

skipjack commented 7 years ago

We had a Lazy Load - React which may be what you're referring to. I guess I'm ok with a Common Frameworks section as long as it mainly provides variations on Getting Started if people are up for maintaining it. I think the key with all these guides is not to reiterate things in previous ones (i.e. state a goal, use a pre-requisite guide if necessary, and stick to that goal) and not try to explain everything (they should really be starting points that give a running start and point to relevant reference/concept docs).

TheDutchCoder commented 7 years ago

@skipjack yeah it's a tough one.

On the one hand I'm all for giving starting points to people, on the other I see your concern re the asks for different frameworks.

The more I think about it, the more I lean towards not adding this in, because practically all topics are covered in the guides themselves (dev-server, config, npm scripts, index.html, etc). Maybe not in Getting Started alone, but in follow up guides.

Adding in a framework is pretty much just npm installing it and using it.

Just my 2 💰

shaodahong commented 7 years ago

You can do the same：

Your First Webpack Project

Before you start, you should install Node

mkdir webpack-project
cd webpack-project
npm init -y

Now your project has a package.json file. It records the information of the project and the dependencies of our installation. Let's install the webpack:

npm i -D webpack

Webpack application:

[Webpack and React]()
[Webpack and Angular]()
[Webpack and Vue]()
[Webpack and Other Frameworks]()
[Webpack and Html]()
[Webpack and Css]()
[Webpack and Stylus]()
[Webpack and TypeScript]()

But I think this is introducing the loader, All Frameworks understood as loader(vue-loader, style-loade, react-loader……)

skipjack commented 7 years ago

Ok I'm going to close as I think this is out of scope (at least currently) but please...

feel free to submit prs adding links framework-specific examples and tutorials
discuss, ask questions, or get involved with the guides work going in #1258

@mrmartineau @arecvlohe definitely keep us posted on the https://github.com/mrmartineau/webpack-recipes work you were discussing. Happy to link to any good starter-kits that are created there. I also should've noted that we do have a starter-kits page which is currently a little hidden, however we can add to it and make it more visible.

arecvlohe commented 7 years ago

I am working on some examples and I will definitely share them with you when they are a bit more complete!

webpack / webpack.js.org

Guides - Minimal Quick Setup Guides for All Frameworks #1394

Quick Setup Guide React

Your First Webpack Project