Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Authoring Libraries #1532

Merged
merged 7 commits into from
Sep 3, 2017
Merged

Authoring Libraries #1532

merged 7 commits into from
Sep 3, 2017

Conversation

marioacc
Copy link
Contributor

@marioacc marioacc commented Aug 21, 2017

Authoring Libraries
A little bit of more explanation was added as well as a warning regarding to issue 4824

@jsf-clabot
Copy link

jsf-clabot commented Aug 21, 2017

CLA assistant check
All committers have signed the CLA.

@skipjack
Copy link
Collaborator

@marioacc awesome thank you for jumping on this, I will review shortly. Can you sign the CLA? Once you've done it once, you should be all set for future contributions from the same GitHub account.

@skipjack
Copy link
Collaborator

@marioacc the first thing I'm noticing is the CI failure. This is due to simple markdown formatting issues:

> [email protected] lint:markdown /home/travis/build/webpack/webpack.js.org
> markdownlint --config ./.markdownlint.json *.md ./content/**/*.md

./content/guides/author-libraries.md: 31: MD031 Fenced code blocks should be surrounded by blank lines
./content/guides/author-libraries.md: 38: MD031 Fenced code blocks should be surrounded by blank lines
./content/guides/author-libraries.md: 94: MD031 Fenced code blocks should be surrounded by blank lines
./content/guides/author-libraries.md: 96: MD031 Fenced code blocks should be surrounded by blank lines
./content/guides/author-libraries.md: 111: MD031 Fenced code blocks should be surrounded by blank lines
./content/guides/author-libraries.md: 221: MD031 Fenced code blocks should be surrounded by blank lines
./content/guides/author-libraries.md: 269: MD031 Fenced code blocks should be surrounded by blank lines
./content/guides/author-libraries.md: 113: MD032 Lists should be surrounded by blank lines
./content/guides/author-libraries.md: 130: MD032 Lists should be surrounded by blank lines
./content/guides/author-libraries.md: 271: MD032 Lists should be surrounded by blank lines

If you could start by resolving those, that would be great.

@marioacc
Copy link
Contributor Author

marioacc commented Aug 23, 2017

@skipjack I already have signed the CLA, so when I click on the Details link, it tells me the CLA is already signed.
I will solve the markdown issues.

@skipjack
Copy link
Collaborator

@marioacc the issue seems to be that one of your commits was authored with a different user (this can happen if you push from work for example). If you rebase on master with your main account, which we have to anyway to resolve the conflicts, it should fix the CLA issues.

Copy link
Collaborator

@TheDutchCoder TheDutchCoder left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 Thanks so much for taking this on!

I have a few items I'd like you to resolve, most of it grammar or spelling actually, so they should be quick to fix!

---

webpack is a tool which can be used to bundle application code and also to bundle library code. If you are the author of a JavaScript library and are looking to streamline your bundle strategy then this document will help you.
webpack is a tool which can be used to bundle application code and also to bundle library code. If you are the author of a JavaScript library and are looking to streamline your bundle strategy then this document will help you with the differents webpack configurations to expose your libraries as you think convenient.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/differents/different

g/as you think/as you think is

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perfect, will make the changes.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@marioacc I would actually probably simplify/rephrase this as:

Aside from applications, webpack can also be used to bundle JavaScript libraries. The following guide is meant for library authors looking to streamline their bundling strategy.

What do you think?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like it. The simpler, the better.


```javascript
import * as webpackNumbers from 'webpack-numbers';

import * as webpackNumbers from 'webpack-numbers';//ES2015 module import
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpicking, but can you add aspace before the comments?
Also decide on whether or not to use a space after the //, as currently both seem to be used ;)

Copy link
Contributor Author

@marioacc marioacc Aug 29, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the other guides the comments are used in the following way:
// Comment text
var someJSCode = {}
Do you mind if I set the comments format in that way?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also decide on whether or not to use a space after the //, as currently both seem to be used ;)

@TheDutchCoder yeah we should probably try to standardize it by padding both sides.

Do you mind if I set the comments format in that way?

That sounds good to me, though I'd probably pad that = sign as well (e.g. var someJSCode = {}) 😜.

...
</script>
</html>
```

The configurations also can expose the library in the next ways:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

g/next/following

The configurations also can expose the library in the next ways:

- Property in the global object, for node.
- Property in the this object.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe use this in back ticks so it shows up as code.

For full library configuration and code please refer to [webpack-library-example](https://github.com/kalcifer/webpack-library-example)


## Configure webpack

Now the agenda is to bundle this library
Now the agenda is to bundle this library achieving the next goals:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure about the word "agenda" here, seems overly formal.
Maybe use "plan" or "idea"?

Copy link
Contributor Author

@marioacc marioacc Aug 29, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "plan" is way better.

- Exposing the library as a variable called `webpackNumbers`.
- Being able to access the library inside Node.js.s

Also, the consumer will be able to access` the library the `next ways:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence has a stray code block and a grammar issue.

How about: "Also, the consumer will be able to access the library in the following ways:"

@@ -166,11 +222,29 @@ module.exports = {
};
```

W>At the moment of webpack 3.5.5, using the next configuration is not working properly as stated in the [issue 4824](https://github.com/webpack/webpack/issues/4824):
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence doesn't flow nicely, how about:

"With webpack 3.5.5, using the following configuration doesn't work properly as stated in issue 4824:"


To make your library available for reuse, add `library` property in webpack configuration.
To make your library available for reuse, add `library` property inside `output` in webpack configuration.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

g/library property/the library property
g/in webpack configuration/in the webpack configuration

@@ -185,7 +259,7 @@ module.exports = {
};
```

This makes your library bundle to be available as a global variable when imported. To make the library compatible with other environments, add `libraryTarget` property to the config.
This makes your library bundle to be available as a global variable named `webpackNumbers` when imported. To make the library compatible with other environments, add `libraryTarget` property to the config. This will add the differents options about how the library can be exposed.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

g/to be available/available
s/differents/different

}
...
};
```

If `library` is set and `libraryTarget` is not, `libraryTarget` defaults to `var` as specified in the [output configuration documentation](/configuration/output). See [`output.libraryTarget`](/configuration/output#output-librarytarget) there for a detailed list of all available options.
You can expose the library in the next ways:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

g/next/following

@skipjack
Copy link
Collaborator

@marioacc thanks for fixing the markdown issues and the CLA thing too. If you could rebase once more on master to resolve the conflicts caused by the restructuring in #1490, that would save me time 🙏. Not a big deal if not, once you make the requested changes we should be able to get this merged 👍 .

@marioacc
Copy link
Contributor Author

@skipjack Can you please take a look at the project, I am not sure If I did the rebase in a proper way.

@skipjack
Copy link
Collaborator

skipjack commented Sep 1, 2017

Ah, yeah something's off here. I'll pop over to you're repo and see if I can fix it. Typically rebasing shouldn't create an extra commit. When you rebase on master you'd typically have to git push --force origin [branch-name] to fix the branch after. It looks like you may have done the rebase correctly but then pulled and pushed instead of just force pushing.

@skipjack
Copy link
Collaborator

skipjack commented Sep 1, 2017

@marioacc the issue should be fixed now. All I did was...

  • Back up your current master branch to a backup branch.
  • Then git reset --hard on master to the most recent commit prior to your changes.
  • Then git cherry-pickd your most recent commits from backup.
  • Then git push -f origin master to update your master branch.

Please double check that everything is as it should be. Like I said, I still have a backup locally so we can restore anything else if necessary. I can't push it to your fork because GitHub only gives me access to your repository for the branch used for the PR.

@marioacc
Copy link
Contributor Author

marioacc commented Sep 1, 2017

@skipjack Thank you very much, I am sorry for the complications my rebase caused.
I took a look over the author-libraries.md in src/content/guides and the old one in content/guides and they are equal.
I will delete the content folder to be in sync with the original webpack repo.

@skipjack
Copy link
Collaborator

skipjack commented Sep 3, 2017

@marioacc somehow things got a bit funky here again. I'll try to resolve and then review, please don't merge or push anything else until that's done.

Minor fixes...

- Code formatting
- Full diffs for most instances
- Some grammar fixes
@skipjack
Copy link
Collaborator

skipjack commented Sep 3, 2017

@marioacc I reviewed and the content was great. Just added one commit to clean things up a bit before I merge.

@TheDutchCoder if you wanted to review again that would be great. I'm going to merge this once the build passes just for the sake of pushing things forward as I think it's in a pretty good state. However if you catch anything, one of us can always submit a follow up PR.

@skipjack skipjack dismissed TheDutchCoder’s stale review September 3, 2017 21:11

To test a build, plus the I believe the review was addressed.

@skipjack
Copy link
Collaborator

skipjack commented Sep 3, 2017

Ok ran the tests locally as we're still seeing network issues on travis that cause the lint:links / hyperlink script to timeout. Everything ran fine with the exception of webpack-contrib/install-webpack-plugin#118 which doesn't relate to this PR. Merging...

@skipjack skipjack merged commit 1c341f7 into webpack:master Sep 3, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants