First stab at SFC to npm documentation #1558

mgdodge · 2018-04-03T21:46:03Z

Feedback welcome!

sdras · 2018-04-05T22:50:16Z

You are awesome! I'm slammed at the moment, but I'll be able to review soon :)

znck · 2018-04-06T13:49:56Z

With 2.2+, we have SSR build which uses string concatenation and as a result it is 2x to 10x faster. If you bundle for browser, the SSR performance is hampered. If you bundle for server, it won't work in browser. So, publishing .vue file is not a bad idea.

In my opinion, there should be a build which can be used directly in browser. Then, a .vue component which uses css in style, html in template and es2015 in script, so that it can be used in most cases.

@yyx990803 WDYT?

mgdodge · 2018-04-07T15:22:28Z

It is true that bundling for just one or the other makes it impossible to deliver just one file. That is why this recipe delivers 3 versions. In the SSR scenario, the file consumed would likely be the module version, or possibly main version. Browser users would consume the unpkg version. All end up with compiled render functions. Does the SSR performance suffer when a component with render function is used?

If shipping the .vue file is important for these use cases, I could rename the section from "Why Shouldn't I Share .vue Files Directly?" to "Can't I Just Share .vue Files Directly?" to temper the suggestion that it is a bad idea. I would also need to include something about the 'files' section of package.json indicating that you can include the .vue file in the npm package? When packaged that way, those wanting the .vue file would have to reference the file explicitly:

import MyComponent from 'my-component/src/my-component.vue';

as the three widely accepted tags of main, module, and unpkg are already taken.

I don't have statistics on how many people use SSR instead of other consumption methods. The npm ecosystem is typically geared towards sharing JS resources, and this recipe is written to that end - presenting a pure JS version in line with the way npm is generally used. I am not opposed to presenting the .vue files as part of the package if that is truly the only way to make SSR remain performant.

yyx990803 · 2018-04-09T19:14:45Z

Thanks for the guide, @mgdodge !

There are a few things we want to resolve for the long run:

Make it possible to use *.vue as the primary format for component distribution. Currently there is a blocker: Pre-processors inside *.vue files would require the consumer to have appropriate build setups. This can be alleviated by us providing a utility to compile raw SFCs down to "plain" SFCs that do not require any special pre-processing.
Before (1) gets resolved, the methods described in this PR can serve as the recommended approach for the time being, with one caveat: SSR. It might be possible to produce an extra SSR dist file, but it requires some build aliasing so that the server build is using the SSR dist files.

posva · 2018-04-08T15:18:33Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+### How does npm know which version to serve to a browser/build process?
+
+The package.json file used by npm really only requires one version (`main`), but as it turns out, we aren't limited to that. By specifying 2 additional versions (`module` and `unpkg`) we can hit that sweet spot and older build processes, newer ES6 compatible ones, and eve browsers directly! A sample package.json would look like this:


even browsers

posva · 2018-04-08T15:21:57Z

src/v2/cookbook/packaing-sfc-for-npm.md

+import MyComponent from 'my-component';
+
+export default {
+  name: 'my-app',


I think name should be omitted for simplicity

posva · 2018-04-08T15:23:40Z

src/v2/cookbook/packaing-sfc-for-npm.md

+  components: {
+    MyComponent,
+  },
+  data() {


I think putting something like

// ... // rest of the component

or even // ... makes it more readable as it becomes valid js

putting both, data() {...} and ... is redundant

posva · 2018-04-08T15:27:10Z

src/v2/cookbook/packaing-sfc-for-npm.md

+export function install(Vue) {
+	if (install.installed) return;
+	install.installed = true;
+	Vue.component('my-component', component);


it's better to register the component as MyComponent so it can be used both ways

mgdodge · 2018-04-09T22:43:52Z

@posva Good catch on the typo, thanks! And the other suggestions are great. Will make the changes shortly.

@yyx990803 I understand the long-term goals you mentioned, and agree with (1) in that it would be nice to present a 'plain' SFC. Forgive my ignorance on the way SSR works (no use cases at my day job,) but I thought in the end all vue components have to be converted to render functions anyway...which is why I thought this would be adequate. Is this not the case?

Regardless, I can update the recipe to include usage of the browser field for the package.json file. According to the package.json spec, we can be creative in this (terribly misnamed, imho) to override the main field.

If my understanding is correct, the following package.json:

{
  "name": "my-component",
  "version": "1.2.3",
  "main": "dist/my-component.umd.js",
  "module": "dist/my-component.esm.js",
  "unpkg": "dist/my-component.min.js",
  "browser": {
    "./sfc": "src/my-component.vue"
  },
  ...
}

should do the trick. Using the component via import/require import MyComponent from 'my-component'; in an older build process will still resolve to main. Someone using a newer one will get module. The unpkg version is still intended for use in script tags. A slight tweak to the import - import MyComponent from 'my-component/sfc'; and it resolves the alias to the .vue file. Lowest impact I can come up with to satisfy all scenarios.

This is all based on some very rudimentary testing, so I would love to have someone more familiar with the SSR process verify this. SFC authors can indicate that the .vue file file may be imported via my-component/sfc for any performance optimization SSR provides.

mgdodge · 2018-04-10T05:14:36Z

@posva @yyx990803 @znck I have updated the PR to address your concerns. Thanks for the advice!

sdras · 2018-04-12T01:12:47Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+Vue components by nature are meant to be re-used. This is easy when the component is only used within a single application. But how can you write a component once and use it in multiple sites/applications? Perhaps the easiest solution is via npm.
+
+By packaging your component to be shared via npm, it can be imported/required into a build process for use full-fledged web applications:


Typo here: "for use in full-fledged.." (Intro is great!)

sdras · 2018-04-12T01:13:33Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+Not only does this help you avoid copy/pasting components around, but it also allows you to give back to the Vue community!
+
+## Can't I Just Share .vue Files Directly?


We should add the backticks around .vue here

sdras · 2018-04-12T01:13:47Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+Vue already allows components to be written as a single file. Because a Single File Component (SFC) is already just one file, you might ask:
+
+> "Why can't people use my .vue file directly? Isn't that the simplest way to share components?"


Just, all the way down :)

sdras · 2018-04-12T01:18:07Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+> "Why can't people use my .vue file directly? Isn't that the simplest way to share components?"
+
+It's true, you could share .vue files directly, and as long as the [Vue build](https://vuejs.org/v2/guide/installation.html#Explanation-of-Different-Builds) being used contains the Vue compiler, that would be enough. For example, string concatenation is used as an optimization in the SSR build, so the .vue file might be preferred in this scenario (see [Packaging Components for npm > SSR Usage](#SSR-Usage) for details). But this excludes anyone who wishes to use the component directly in a browser via `<script>` tag, anyone who uses a runtime-only build, or a build process which doesn't understand what to do with .vue files.


I like how conversational this paragraph is, however the flow is a bit strange. "and as long as the build you are using contains the vue complier, that would be enough."

Later, maybe replacing "But" with "However," at the beginning of the sentence.

I will rework this paragraph a little to change the flow.

sdras · 2018-04-12T01:20:18Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+Compatible bundlers see the `browser` definition in package.json and translate requests for `my-component/sfc` into `my-component/src/my-component.vue`, resulting in the original .vue file being used instead. Now the SSR process can use the string concatenation optimizations it needs to for a boost in performance.
+
+> Note: When using .vue components directly, pay attention to any type of pre-processing required by `script` and `style` tags. These dependencies will be passed on to users. Consider providing 'plain' SFCs to keep things as light as possible.


Great callout.

sdras · 2018-04-12T01:21:27Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+### What does my packaged component look like?
+
+Depending on how your component is being used, it needs to be exposed as either a CommonJS/UMD javascript module, an ES6 javascript module, or in the case of a `<script>` tag, it will be automatically loaded into Vue via `Vue.use(...)` so it's immediately available to the page. This is accomplished by a simple wrapper.js file which handles the module export and auto-install. That wrapper, in its entirety, looks like this:


It would be great to link off to docs for CommonJS and ES6 modules here.

sdras · 2018-04-12T01:22:28Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+In other words, do all of your development in whatever way you are comfortable. The things outlined in this recipe are more like 'finishing touches' than a full dev process.
+
+## When to Avoid this Pattern


This is a great "when to avoid this pattern" section, thank you.

sdras · 2018-04-12T01:24:58Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+At the time this recipe was written, Vue CLI 3 was itself in beta. This version of the CLI comes with a built-in `library` build mode, which creates CommonJS and UMD versions of a component. This might be adequate for your use cases, though you will still need to make sure your package.json file points to `main` and `unpkg` properly. Also, there will be no ES6 `module` output unless that capability is added to the CLI before its release or via plugin.
+
+The process here is the result of what was learned looking at other vue modules which have already been published by the greater vue community. The reason for the recipe was because there was a lack of well documented patterns for preparing a component for npm.


I would omit this paragraph, though I appreciate your course of action, it sounds unnecessary and separate from rest of the recipe.

sdras · 2018-04-12T01:25:51Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+## Acknowledgements
+
+This recipe is the result of a lightning talk given by [Mike Dodge](https://twitter.com/mgdodgeycode) at VueConf.us in March 2018. He has published a utility to npm which will quickly scaffold a sample SFC using this recipe. You can download the utility, [vue-sfc-rollup](https://www.npmjs.com/package/vue-sfc-rollup), from npm. You can also [clone the repo](https://github.com/mgdodge/vue-sfc-rollup) and customize it to fill your needs.


"to fill it with your needs" is odd phrasing, "customize it" would suffice.

sdras · 2018-04-12T01:28:44Z

Looking good! I reviewed for clarity and flow, I'm giving it one more round soon while reproducing. You can start on those edits though, if you want to push it forward in the meantime. :)

mgdodge · 2018-05-02T16:51:12Z

Just curious on the status of this.

…to cookbook-sfc-to-npm # Conflicts: # src/v2/cookbook/packaing-sfc-for-npm.md

sdras · 2018-05-02T20:56:48Z

Thank you for the ping, we haven't forgotten about you! I have MSFT Build coming up, and can review it after. Thanks for your patience.

sdras

It's looking clean! I have a few points of clarification but we're getting close 👍

sdras · 2018-05-19T18:07:48Z

src/v2/cookbook/packaing-sfc-for-npm.md

+---
+title: Packaging Vue Components for npm
+type: cookbook
+order: 10


We have order 10 and 11 now, this would need to be 12

sdras · 2018-05-19T18:09:26Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+### SSR Usage
+
+You might have noticed something interesting - browsers aren't going to be using the `browser` version! That's because this field is actually intended to allow authors to provide [hints to bundlers](https://github.com/defunctzombie/package-browser-field-spec#spec) which in turn create their own packages for client side use. With a little creativity, this field allows us to map an alias to the `.vue` file itself. For example:


Style note- I do like the use of exclamation points to convey excitement but when they're used back to back like this, it seems a little over the top. I'd drop the second one here.

sdras · 2018-05-19T18:10:00Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+Compatible bundlers see the `browser` definition in package.json and translate requests for `my-component/sfc` into `my-component/src/my-component.vue`, resulting in the original `.vue` file being used instead. Now the SSR process can use the string concatenation optimizations it needs to for a boost in performance.
+
+> Note: When using `.vue` components directly, pay attention to any type of pre-processing required by `script` and `style` tags. These dependencies will be passed on to users. Consider providing 'plain' SFCs to keep things as light as possible.


Can you please put this in a <p class="tip"></tip>? That's our docs standard.

sdras · 2018-05-19T18:12:35Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+### How do I make multiple versions of my component?
+
+There is no need to write your module multiple times. It is possible to prepare all 3 versions of your module in one step, in a matter of seconds. The example here uses [Rollup](https://rollupjs.org) due to its minimal configuration, but similar configuration is possible with other build tools. The package.json `scripts` section can be updated with a single entry for each build target, and a more generic `build` script that runs them all in one pass. The sample package.json file now looks like this:


Should we mention webpack here as well? It's also fine as is.

It might be worth just linking off to a resource like this, in case people are interested: https://medium.com/webpack/webpack-and-rollup-the-same-but-different-a41ad427058c. Your call, though.

Not mentioning webpack, but will add link to the article - I did come across it while researching.

sdras · 2018-05-19T18:16:34Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+## Alternative Patterns
+
+At the time this recipe was written, Vue CLI 3 was itself in beta. This version of the CLI comes with a built-in `library` build mode, which creates CommonJS and UMD versions of a component. This might be adequate for your use cases, though you will still need to make sure your package.json file points to `main` and `unpkg` properly. Also, there will be no ES6 `module` output unless that capability is added to the CLI before its release or via plugin.


Is it worth mentioning https://github.com/vuejs/rollup-plugin-vue?

Sorry, my bad, I confused this with another library.

sdras · 2018-05-19T18:17:43Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+## Packaging Components for npm
+
+For the purposes of this section, assume the following file structure:


this type of explanation of structure before diving in is really useful to people reading 👍

sdras · 2018-05-19T18:24:51Z

src/v2/cookbook/packaing-sfc-for-npm.md

+}
+```
+
+That is all that is required in package.json to get up and running. Now, all that is needed is a small wrapper to export/auto-install the actual SFC, plus a mimimal Rollup configuration, and we're set!


Hm, when we say "this is all that is needed" which is repeated twice here, it may be hard on the person reading it if they are just grasping these concepts. Consider this post. I believe you're trying to be supportive of the reader, but it may come across the other way. Can you please consider another way of phrasing one of these two sentences?

sdras · 2018-05-19T18:26:32Z

src/v2/cookbook/packaing-sfc-for-npm.md

+  },
+  ...
+}
+```


One thing I find lacking here reading through is how you created this base package.json. Did you use a generator? Are you going off of another file? How are you deciding what versions should be used for each? Are you manually looking at the current version of LTS in terminal? These are some things that might deserve a quick couple of sentences to clarify to be most helpful.

Adding another paragraph explaining that this package.json illustrates a starting point, and that versions can/should be kept up to date as necessary.

mgdodge

New revision forthcoming to address these

mgdodge · 2018-05-21T18:48:12Z

src/v2/cookbook/packaing-sfc-for-npm.md

+---
+title: Packaging Vue Components for npm
+type: cookbook
+order: 10


mgdodge · 2018-05-21T18:48:38Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+### SSR Usage
+
+You might have noticed something interesting - browsers aren't going to be using the `browser` version! That's because this field is actually intended to allow authors to provide [hints to bundlers](https://github.com/defunctzombie/package-browser-field-spec#spec) which in turn create their own packages for client side use. With a little creativity, this field allows us to map an alias to the `.vue` file itself. For example:


mgdodge · 2018-05-21T18:48:57Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+Compatible bundlers see the `browser` definition in package.json and translate requests for `my-component/sfc` into `my-component/src/my-component.vue`, resulting in the original `.vue` file being used instead. Now the SSR process can use the string concatenation optimizations it needs to for a boost in performance.
+
+> Note: When using `.vue` components directly, pay attention to any type of pre-processing required by `script` and `style` tags. These dependencies will be passed on to users. Consider providing 'plain' SFCs to keep things as light as possible.


mgdodge · 2018-05-21T18:49:45Z

src/v2/cookbook/packaing-sfc-for-npm.md

+
+### How do I make multiple versions of my component?
+
+There is no need to write your module multiple times. It is possible to prepare all 3 versions of your module in one step, in a matter of seconds. The example here uses [Rollup](https://rollupjs.org) due to its minimal configuration, but similar configuration is possible with other build tools. The package.json `scripts` section can be updated with a single entry for each build target, and a more generic `build` script that runs them all in one pass. The sample package.json file now looks like this:


Not mentioning webpack, but will add link to the article - I did come across it while researching.

mgdodge · 2018-05-21T18:50:41Z

src/v2/cookbook/packaing-sfc-for-npm.md

+  },
+  ...
+}
+```


Adding another paragraph explaining that this package.json illustrates a starting point, and that versions can/should be kept up to date as necessary.

mgdodge · 2018-05-21T18:51:00Z

src/v2/cookbook/packaing-sfc-for-npm.md

+}
+```
+
+That is all that is required in package.json to get up and running. Now, all that is needed is a small wrapper to export/auto-install the actual SFC, plus a mimimal Rollup configuration, and we're set!


sdras · 2018-05-23T06:56:36Z

Looks like all that we're missing from you are those details about the package.json and we can merge! Nice job.

mgdodge · 2018-05-24T20:08:25Z

@sdras My last two updates addressed the package.json request you made. There are now two paragraphs - one where I first introduce the file structure and package.json, and the second when I am listing build scripts and dependencies.

Hopefully there isn't anything more that needs to be said. I'm not sure what you meant by looking at LTS in terminal...this stuff should work with any version of node, AFAIK.

@sdras

* Update unit-testing-vue-components.md (vuejs#1623) * Fixed a typo (vuejs#1625) Removed an extra 's' to fix a grammatical mistake * fix a typo (vuejs#1627) * Update v-for list example (vuejs#1628) * Add presentation role to style-only li item * fix: code snippet language (close vuejs#1617) (vuejs#1626) * Update todo-list-example for a11y (vuejs#1630) * Update todo-list-example for a11y * Implement review suggestions * Use explicit label instead of aria-label * Move v-model directive to top for improved readability * change NODE_ENV to follow recommendations from webpack (vuejs#1622) * change NODE_ENV to follow recommendations from weback * Update deployment.md * note that modes are not available in transition groups, fixes vuejs#1619 * add examples for in API doc * add comparison note about react-like libraries * Update components.md (vuejs#1632) * Update components.md * Update components.md * improve flow of single root component section * cookbook entry for storage (vuejs#1550) * cookbook entry for storage * minor tweak * updates to article * updates to article * maybe the last tweak * the honest to god really last mod * Update index.md (vuejs#1634) * docs(guide/comparison): correct size stat of Angular CLI project (vuejs#1638) * Update client-side-storage.md (vuejs#1640) * Update creating-custom-scroll-directives.md (vuejs#1639) * chore: update ad code * remove unnecessary word 'know' (vuejs#1641) * Updated broken links for the Vue Test Utils documentation. (vuejs#1643) * Reorganize component props to introduce prop types earlier, fixes vuejs#1644 (vuejs#1646) @BlitZz96 brought up a good point in [this issue](vuejs#1644) about users lacking the necessary background knowledge to fully understand Passing Static and Dynamic Props, at least as it relates to booleans and potentially other types in the future. To fix this, I added a new Prop Types section right before it. * First stab at SFC to npm documentation (vuejs#1558) * First stab at SFC to npm documentation * Clean up sample code, clarify .vue usage with SSR builds * Run build tasks in parallel, fix dependency order * Backtick all instances of .vue, minor edits for clarity * Fix typo on link * Update url to vue-sfc-rollup utility in acknowledgements * Fix order, other edits suggested by @sdras * Additional explanation about sfc-to-npm recipe package.json * Rename packaing-sfc-for-npm.md to packaging-sfc-for-npm.md (vuejs#1652) * Update link in comparison guide (vuejs#1653) The phrase "These state management patterns and even Redux itself can be easily integrated into Vue applications" has a link to a deprecated project. Instead I link to a yarnpkg.com search I saw used in https://vuejs.org/v2/guide/state-management.html, which links all "redux vue" projects (so it's always up to date) * chore: update vue version * Fix link to docs on custom inputs (vuejs#1660) The old link redirected me to https://vuejs.org/v2/guide/components-custom-events.html#Binding-Native-Events-to-Components which was unexpected. I think the correct link is https://vuejs.org/v2/guide/components.html#Using-v-model-on-Components as per this change. * correct wrong link (vuejs#1661) * Update events.md correct wrong link * Update events.md correct wrong link * Feature/vuemeetups (vuejs#1665) * feature: Add link to VueMeetups * feature: Add section on becoming a community leader * minor tweaks to meetup section * Added details about Lifecycle Hooks (vuejs#1664) * Added details about Lifecycle Hooks Mostly a clarification for beginners without prior knowledge about what Lifecycle hooks are. Makes it easier to understand when perhaps only knowing that the developer has a `mounted()` hook. I left out the function syntax because of generality. Add if it makes more sense to add. I am not fully knowledgable in Vue yet. * add (de)activated to lifecycle hooks list in style guide * improve comparisons react scaling down section * add text versions of image code examples * remove extra comma in components * TypeScript project generation in @vue/cli 3.0 (vuejs#1668) * TypeScript project generation in @vue/cli 3.0 update information about generating TypeScript project using new @vue/cli 3.0 * tweaks to Vue CLI 3 TypeScript support docs * chore: update sponsors * Sylvain and Forresst feedbacks Signed-off-by: MachinisteWeb <[email protected]> * @ForrestT and @raisonblue feedback Signed-off-by: MachinisteWeb <[email protected]> * Feedback of @rspt Signed-off-by: MachinisteWeb <[email protected]>

@sdras

* Update unit-testing-vue-components.md (vuejs#1623) * Fixed a typo (vuejs#1625) Removed an extra 's' to fix a grammatical mistake * fix a typo (vuejs#1627) * Update v-for list example (vuejs#1628) * Add presentation role to style-only li item * fix: code snippet language (close vuejs#1617) (vuejs#1626) * Update todo-list-example for a11y (vuejs#1630) * Update todo-list-example for a11y * Implement review suggestions * Use explicit label instead of aria-label * Move v-model directive to top for improved readability * change NODE_ENV to follow recommendations from webpack (vuejs#1622) * change NODE_ENV to follow recommendations from weback * Update deployment.md * note that modes are not available in transition groups, fixes vuejs#1619 * add examples for in API doc * add comparison note about react-like libraries * Update components.md (vuejs#1632) * Update components.md * Update components.md * improve flow of single root component section * cookbook entry for storage (vuejs#1550) * cookbook entry for storage * minor tweak * updates to article * updates to article * maybe the last tweak * the honest to god really last mod * Update index.md (vuejs#1634) * docs(guide/comparison): correct size stat of Angular CLI project (vuejs#1638) * Update client-side-storage.md (vuejs#1640) * Update creating-custom-scroll-directives.md (vuejs#1639) * chore: update ad code * remove unnecessary word 'know' (vuejs#1641) * Updated broken links for the Vue Test Utils documentation. (vuejs#1643) * Reorganize component props to introduce prop types earlier, fixes vuejs#1644 (vuejs#1646) @BlitZz96 brought up a good point in [this issue](vuejs#1644) about users lacking the necessary background knowledge to fully understand Passing Static and Dynamic Props, at least as it relates to booleans and potentially other types in the future. To fix this, I added a new Prop Types section right before it. * First stab at SFC to npm documentation (vuejs#1558) * First stab at SFC to npm documentation * Clean up sample code, clarify .vue usage with SSR builds * Run build tasks in parallel, fix dependency order * Backtick all instances of .vue, minor edits for clarity * Fix typo on link * Update url to vue-sfc-rollup utility in acknowledgements * Fix order, other edits suggested by @sdras * Additional explanation about sfc-to-npm recipe package.json * Rename packaing-sfc-for-npm.md to packaging-sfc-for-npm.md (vuejs#1652) * Update link in comparison guide (vuejs#1653) The phrase "These state management patterns and even Redux itself can be easily integrated into Vue applications" has a link to a deprecated project. Instead I link to a yarnpkg.com search I saw used in https://vuejs.org/v2/guide/state-management.html, which links all "redux vue" projects (so it's always up to date) * chore: update vue version * Fix link to docs on custom inputs (vuejs#1660) The old link redirected me to https://vuejs.org/v2/guide/components-custom-events.html#Binding-Native-Events-to-Components which was unexpected. I think the correct link is https://vuejs.org/v2/guide/components.html#Using-v-model-on-Components as per this change. * correct wrong link (vuejs#1661) * Update events.md correct wrong link * Update events.md correct wrong link * Feature/vuemeetups (vuejs#1665) * feature: Add link to VueMeetups * feature: Add section on becoming a community leader * minor tweaks to meetup section * Added details about Lifecycle Hooks (vuejs#1664) * Added details about Lifecycle Hooks Mostly a clarification for beginners without prior knowledge about what Lifecycle hooks are. Makes it easier to understand when perhaps only knowing that the developer has a `mounted()` hook. I left out the function syntax because of generality. Add if it makes more sense to add. I am not fully knowledgable in Vue yet. * add (de)activated to lifecycle hooks list in style guide * improve comparisons react scaling down section * add text versions of image code examples * remove extra comma in components * TypeScript project generation in @vue/cli 3.0 (vuejs#1668) * TypeScript project generation in @vue/cli 3.0 update information about generating TypeScript project using new @vue/cli 3.0 * tweaks to Vue CLI 3 TypeScript support docs * chore: update sponsors * Sylvain and Forresst feedbacks Signed-off-by: MachinisteWeb <[email protected]> * chore: update sponsors * update CLI docs link * add Scrimba links for preview * @ForrestT and @raisonblue feedback Signed-off-by: MachinisteWeb <[email protected]> * Feedback of @rspt Signed-off-by: MachinisteWeb <[email protected]> * Fix example indentation in the Unit Testing Vue Components recipe (vuejs#1683) * Update debugging-in-vscode.md (vuejs#1662) * Added link to vuemeetups.org to the ecosystem drop-down menu on website. (vuejs#1685) * Correct mistake of Migration from Vue 1.x (vuejs#1686) * Fix code style in Form Validation recipe (vuejs#1682) * Fix code style in Form Validation recipe * More style code slight improvement in Form Validation recipe * Fix code style in Client-Side Storage recipe (vuejs#1690) * [Doc EN]: `typescript.md` (vuejs#1679) * New in with + symbol Signed-off-by: Bruno Lesieur <[email protected]> * Review of 2.5.0 doc Signed-off-by: Bruno Lesieur <[email protected]> * Review Signed-off-by: Bruno Lesieur <[email protected]> * Fix syntax typo Signed-off-by: Bruno Lesieur <[email protected]> * Add space between new line of documentation Signed-off-by: MachinisteWeb <[email protected]> * Add @posva review Signed-off-by: MachinisteWeb <[email protected]> * Add french str Signed-off-by: MachinisteWeb <[email protected]> * Change directeur to director Signed-off-by: MachinisteWeb <[email protected]> * Fix EN doc Signed-off-by: MachinisteWeb <[email protected]> * Subtitle for typescript.md Signed-off-by: MachinisteWeb <[email protected]> * Revert instance.md Signed-off-by: MachinisteWeb <[email protected]> * [cookbook] Dockerize Vue.js App (vuejs#1483) * First draft with 'Simple Example' section * Fix typo on Docker 'build' command * Fix copy of multiple files * Remove unnecessary whitespace * Fix typo in webpack template link * First draft of 'Real-World Example' * Update 'Real-World Example' with multi-stage build * Add 'Why Dockerize a Vue.js App?' section * Rename 'Why Dockerize a Vue.js App?' as 'Additinal Context' * Add 'Alternative Patterns' section * Minor fix on 'Alternative Patterns' * Fixed typo * Update order to avoid collision with other cookbooks * Clarify why NGINX in real-world example * Update debugging-in-vscode.md (vuejs#1663) * remove outdated information about polymer from comparison * update React comparison status * Remove extra part Signed-off-by: Haeresis <[email protected]> * Remove extra content from api/index.md Signed-off-by: Haeresis <[email protected]> * Remove extra merge Signed-off-by: Haeresis <[email protected]>

@sdras

* Update unit-testing-vue-components.md (vuejs#1623) * Fixed a typo (vuejs#1625) Removed an extra 's' to fix a grammatical mistake * fix a typo (vuejs#1627) * Update v-for list example (vuejs#1628) * Add presentation role to style-only li item * fix: code snippet language (close vuejs#1617) (vuejs#1626) * Update todo-list-example for a11y (vuejs#1630) * Update todo-list-example for a11y * Implement review suggestions * Use explicit label instead of aria-label * Move v-model directive to top for improved readability * change NODE_ENV to follow recommendations from webpack (vuejs#1622) * change NODE_ENV to follow recommendations from weback * Update deployment.md * note that modes are not available in transition groups, fixes vuejs#1619 * add examples for in API doc * add comparison note about react-like libraries * Update components.md (vuejs#1632) * Update components.md * Update components.md * improve flow of single root component section * cookbook entry for storage (vuejs#1550) * cookbook entry for storage * minor tweak * updates to article * updates to article * maybe the last tweak * the honest to god really last mod * Update index.md (vuejs#1634) * docs(guide/comparison): correct size stat of Angular CLI project (vuejs#1638) * Update client-side-storage.md (vuejs#1640) * Update creating-custom-scroll-directives.md (vuejs#1639) * chore: update ad code * remove unnecessary word 'know' (vuejs#1641) * Updated broken links for the Vue Test Utils documentation. (vuejs#1643) * Reorganize component props to introduce prop types earlier, fixes vuejs#1644 (vuejs#1646) @BlitZz96 brought up a good point in [this issue](vuejs#1644) about users lacking the necessary background knowledge to fully understand Passing Static and Dynamic Props, at least as it relates to booleans and potentially other types in the future. To fix this, I added a new Prop Types section right before it. * First stab at SFC to npm documentation (vuejs#1558) * First stab at SFC to npm documentation * Clean up sample code, clarify .vue usage with SSR builds * Run build tasks in parallel, fix dependency order * Backtick all instances of .vue, minor edits for clarity * Fix typo on link * Update url to vue-sfc-rollup utility in acknowledgements * Fix order, other edits suggested by @sdras * Additional explanation about sfc-to-npm recipe package.json * Rename packaing-sfc-for-npm.md to packaging-sfc-for-npm.md (vuejs#1652) * Update link in comparison guide (vuejs#1653) The phrase "These state management patterns and even Redux itself can be easily integrated into Vue applications" has a link to a deprecated project. Instead I link to a yarnpkg.com search I saw used in https://vuejs.org/v2/guide/state-management.html, which links all "redux vue" projects (so it's always up to date) * chore: update vue version * Fix link to docs on custom inputs (vuejs#1660) The old link redirected me to https://vuejs.org/v2/guide/components-custom-events.html#Binding-Native-Events-to-Components which was unexpected. I think the correct link is https://vuejs.org/v2/guide/components.html#Using-v-model-on-Components as per this change. * correct wrong link (vuejs#1661) * Update events.md correct wrong link * Update events.md correct wrong link * Feature/vuemeetups (vuejs#1665) * feature: Add link to VueMeetups * feature: Add section on becoming a community leader * minor tweaks to meetup section * Added details about Lifecycle Hooks (vuejs#1664) * Added details about Lifecycle Hooks Mostly a clarification for beginners without prior knowledge about what Lifecycle hooks are. Makes it easier to understand when perhaps only knowing that the developer has a `mounted()` hook. I left out the function syntax because of generality. Add if it makes more sense to add. I am not fully knowledgable in Vue yet. * add (de)activated to lifecycle hooks list in style guide * improve comparisons react scaling down section * add text versions of image code examples * remove extra comma in components * TypeScript project generation in @vue/cli 3.0 (vuejs#1668) * TypeScript project generation in @vue/cli 3.0 update information about generating TypeScript project using new @vue/cli 3.0 * tweaks to Vue CLI 3 TypeScript support docs * chore: update sponsors * chore: update sponsors * update CLI docs link * add Scrimba links for preview * Fix example indentation in the Unit Testing Vue Components recipe (vuejs#1683) * Update debugging-in-vscode.md (vuejs#1662) * Added link to vuemeetups.org to the ecosystem drop-down menu on website. (vuejs#1685) * Correct mistake of Migration from Vue 1.x (vuejs#1686) * Fix code style in Form Validation recipe (vuejs#1682) * Fix code style in Form Validation recipe * More style code slight improvement in Form Validation recipe * Fix code style in Client-Side Storage recipe (vuejs#1690) * [Doc EN]: `typescript.md` (vuejs#1679) * New in with + symbol Signed-off-by: Bruno Lesieur <[email protected]> * Review of 2.5.0 doc Signed-off-by: Bruno Lesieur <[email protected]> * Review Signed-off-by: Bruno Lesieur <[email protected]> * Fix syntax typo Signed-off-by: Bruno Lesieur <[email protected]> * Add space between new line of documentation Signed-off-by: MachinisteWeb <[email protected]> * Add @posva review Signed-off-by: MachinisteWeb <[email protected]> * Add french str Signed-off-by: MachinisteWeb <[email protected]> * Change directeur to director Signed-off-by: MachinisteWeb <[email protected]> * Fix EN doc Signed-off-by: MachinisteWeb <[email protected]> * Subtitle for typescript.md Signed-off-by: MachinisteWeb <[email protected]> * Revert instance.md Signed-off-by: MachinisteWeb <[email protected]> * [cookbook] Dockerize Vue.js App (vuejs#1483) * First draft with 'Simple Example' section * Fix typo on Docker 'build' command * Fix copy of multiple files * Remove unnecessary whitespace * Fix typo in webpack template link * First draft of 'Real-World Example' * Update 'Real-World Example' with multi-stage build * Add 'Why Dockerize a Vue.js App?' section * Rename 'Why Dockerize a Vue.js App?' as 'Additinal Context' * Add 'Alternative Patterns' section * Minor fix on 'Alternative Patterns' * Fixed typo * Update order to avoid collision with other cookbooks * Clarify why NGINX in real-world example * Update debugging-in-vscode.md (vuejs#1663) * remove outdated information about polymer from comparison * update React comparison status * chore: adjust sponsor placement * chore: sponsor meta * adjust sponsor naming on pages * Add alt text to images to help with screen reader accessibility (vuejs#1676) * chore: update sponsors * chore: add tidelift

First stab at SFC to npm documentation

03a1f4c

sdras added the cookbook label Apr 5, 2018

posva reviewed Apr 9, 2018

View reviewed changes

Clean up sample code, clarify .vue usage with SSR builds

13df2d7

Run build tasks in parallel, fix dependency order

3c8e4e3

sdras reviewed Apr 12, 2018

View reviewed changes

mgdodge added 2 commits April 12, 2018 08:04

Backtick all instances of .vue, minor edits for clarity

0d5f730

Fix typo on link

4fd4ed3

Michael Dodge added 2 commits May 2, 2018 12:44

Update url to vue-sfc-rollup utility in acknowledgements

b384983

Merge branch 'cookbook-sfc-to-npm' of github.com:mgdodge/vuejs.org in…

5b0015a

…to cookbook-sfc-to-npm # Conflicts: # src/v2/cookbook/packaing-sfc-for-npm.md

mgdodge mentioned this pull request May 17, 2018

Recipe for Vuejs.org Cookbook? team-innovation/vue-sfc-rollup#1

Closed

sdras suggested changes May 19, 2018

View reviewed changes

mgdodge commented May 21, 2018

View reviewed changes

Fix order, other edits suggested by @sdras

d90dd16

Additional explanation about sfc-to-npm recipe package.json

a45233d

sdras approved these changes May 25, 2018

View reviewed changes

sdras merged commit dc9b6cb into vuejs:master May 25, 2018

vuejs deleted a comment from mgdodge May 25, 2018

mgdodge deleted the cookbook-sfc-to-npm branch June 5, 2018 16:10

Lahori-Jawan mentioned this pull request Jul 26, 2018

How to externalilze dependency and Use component with it team-innovation/vue-sfc-rollup#5

Closed


		### How does npm know which version to serve to a browser/build process?

		The package.json file used by npm really only requires one version (`main`), but as it turns out, we aren't limited to that. By specifying 2 additional versions (`module` and `unpkg`) we can hit that sweet spot and older build processes, newer ES6 compatible ones, and eve browsers directly! A sample package.json would look like this:


		Vue components by nature are meant to be re-used. This is easy when the component is only used within a single application. But how can you write a component once and use it in multiple sites/applications? Perhaps the easiest solution is via npm.

		By packaging your component to be shared via npm, it can be imported/required into a build process for use full-fledged web applications:


		Not only does this help you avoid copy/pasting components around, but it also allows you to give back to the Vue community!

		## Can't I Just Share .vue Files Directly?


		Vue already allows components to be written as a single file. Because a Single File Component (SFC) is already just one file, you might ask:

		> "Why can't people use my .vue file directly? Isn't that the simplest way to share components?"


		> "Why can't people use my .vue file directly? Isn't that the simplest way to share components?"

		It's true, you could share .vue files directly, and as long as the [Vue build](https://vuejs.org/v2/guide/installation.html#Explanation-of-Different-Builds) being used contains the Vue compiler, that would be enough. For example, string concatenation is used as an optimization in the SSR build, so the .vue file might be preferred in this scenario (see [Packaging Components for npm > SSR Usage](#SSR-Usage) for details). But this excludes anyone who wishes to use the component directly in a browser via `<script>` tag, anyone who uses a runtime-only build, or a build process which doesn't understand what to do with .vue files.


		Compatible bundlers see the `browser` definition in package.json and translate requests for `my-component/sfc` into `my-component/src/my-component.vue`, resulting in the original .vue file being used instead. Now the SSR process can use the string concatenation optimizations it needs to for a boost in performance.

		> Note: When using .vue components directly, pay attention to any type of pre-processing required by `script` and `style` tags. These dependencies will be passed on to users. Consider providing 'plain' SFCs to keep things as light as possible.


		### What does my packaged component look like?

		Depending on how your component is being used, it needs to be exposed as either a CommonJS/UMD javascript module, an ES6 javascript module, or in the case of a `<script>` tag, it will be automatically loaded into Vue via `Vue.use(...)` so it's immediately available to the page. This is accomplished by a simple wrapper.js file which handles the module export and auto-install. That wrapper, in its entirety, looks like this:


		In other words, do all of your development in whatever way you are comfortable. The things outlined in this recipe are more like 'finishing touches' than a full dev process.

		## When to Avoid this Pattern


		At the time this recipe was written, Vue CLI 3 was itself in beta. This version of the CLI comes with a built-in `library` build mode, which creates CommonJS and UMD versions of a component. This might be adequate for your use cases, though you will still need to make sure your package.json file points to `main` and `unpkg` properly. Also, there will be no ES6 `module` output unless that capability is added to the CLI before its release or via plugin.

		The process here is the result of what was learned looking at other vue modules which have already been published by the greater vue community. The reason for the recipe was because there was a lack of well documented patterns for preparing a component for npm.


		## Acknowledgements

		This recipe is the result of a lightning talk given by [Mike Dodge](https://twitter.com/mgdodgeycode) at VueConf.us in March 2018. He has published a utility to npm which will quickly scaffold a sample SFC using this recipe. You can download the utility, [vue-sfc-rollup](https://www.npmjs.com/package/vue-sfc-rollup), from npm. You can also [clone the repo](https://github.com/mgdodge/vue-sfc-rollup) and customize it to fill your needs.


		### SSR Usage

		You might have noticed something interesting - browsers aren't going to be using the `browser` version! That's because this field is actually intended to allow authors to provide [hints to bundlers](https://github.com/defunctzombie/package-browser-field-spec#spec) which in turn create their own packages for client side use. With a little creativity, this field allows us to map an alias to the `.vue` file itself. For example:


		Compatible bundlers see the `browser` definition in package.json and translate requests for `my-component/sfc` into `my-component/src/my-component.vue`, resulting in the original `.vue` file being used instead. Now the SSR process can use the string concatenation optimizations it needs to for a boost in performance.

		> Note: When using `.vue` components directly, pay attention to any type of pre-processing required by `script` and `style` tags. These dependencies will be passed on to users. Consider providing 'plain' SFCs to keep things as light as possible.


		### How do I make multiple versions of my component?

		There is no need to write your module multiple times. It is possible to prepare all 3 versions of your module in one step, in a matter of seconds. The example here uses [Rollup](https://rollupjs.org) due to its minimal configuration, but similar configuration is possible with other build tools. The package.json `scripts` section can be updated with a single entry for each build target, and a more generic `build` script that runs them all in one pass. The sample package.json file now looks like this:


		## Alternative Patterns

		At the time this recipe was written, Vue CLI 3 was itself in beta. This version of the CLI comes with a built-in `library` build mode, which creates CommonJS and UMD versions of a component. This might be adequate for your use cases, though you will still need to make sure your package.json file points to `main` and `unpkg` properly. Also, there will be no ES6 `module` output unless that capability is added to the CLI before its release or via plugin.


		## Packaging Components for npm

		For the purposes of this section, assume the following file structure:

First stab at SFC to npm documentation #1558

First stab at SFC to npm documentation #1558

Conversation

mgdodge commented Apr 3, 2018

sdras commented Apr 5, 2018

znck commented Apr 6, 2018

mgdodge commented Apr 7, 2018 • edited Loading

yyx990803 commented Apr 9, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mgdodge commented Apr 9, 2018

mgdodge commented Apr 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdras Apr 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdras Apr 12, 2018 • edited Loading

Choose a reason for hiding this comment

sdras commented Apr 12, 2018

mgdodge commented May 2, 2018

sdras commented May 2, 2018

sdras left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mgdodge left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdras commented May 23, 2018

mgdodge commented May 24, 2018

mgdodge commented Apr 7, 2018 •

edited

Loading

sdras Apr 12, 2018 •

edited

Loading

sdras Apr 12, 2018 •

edited

Loading