Add a `library` or `plugin` option to `vue create`

kestred commented 5 years ago

Updated: Dec 1, 2018 (per conservation)

What problem does this feature solve?

If someone is setting out to build a library with more than one component in it, there isn't a clear correct way to do so. Similarly, there are no best practices provided by the community to stay consistent (or just avoid having to make decisions yourself when rapidly prototyping).

A library option in vue create would create a project intended to be compiled and distributed as a Library/Plugin rather than an Application.

Workflow Differences

A library project typically doesn't have an App.vue or an index.html, and this changes the way that you might want to develop the application. Notably, vue-cli-service serve doesn't necessarily have anything "canonical" to serve.

A few workflows that might be common:
- Having a demo, test, or docs website that renders the application (possibly using vue-cli-service serve).
- Having a static page that loads files from dist, supported by auto re-build (something like vue-cli-service watch?).
Many library projects typically commit their dist by default (or at least as part of publishing) rather than ignoring it in .gitignore.

What does the proposed API look like?

A vue create --target lib or vue create --target plugin would be added as a command line option

Changes to "Manually select features"

These feature options might be removed:

Router
Progressive Web App

Changes to code generation

The public directory would not be generated.
The App.vue file would not be generated.
Instead of generating, public and App.vue, an example directory would be generated with index.html, main.{js,ts}, and App.vue and a dependency on the library itself.
- Possibly this directory would have its own package.json
- Possibly there could be questions during an interactive vue create to generate an example vs docs, or other testing website stub.
- Possibly the generated website could be pre-organized to help document the plugin.

A lib.{js,ts} file would be generated instead of main.{js,ts}, perhaps something like (e.g. for Typescript)

const plugin: PluginObject<void> = {
install(Vue: VueConstructor) {
  // Vue.component("MyComponent", MyComponent);
  // Vue.component("MyOtherComponent", MyOtherComponent);
}
};
export default plugin;

The package.json's build script would be replaced with vue-cli-service build --target lib --name MY_LIBRARY_NAME src/lib.ts.
The package.json would either not include a serve script, or the serve task/script would be updated to serve the example application for the library.
The yarn.lock and package-lock.json patterns would be added to the .gitignore file.

Additionally, any other code generation changes as appropriate according to community best practices.

Open Questions

Possibly vue-cli and vue-cli-service would be updated to support rollup rather than relying on the current vue-cli-service build --target lib.
Possibly the dist directory would be removed from the .gitignore by default.
- Alternatively is there a better way to configure the repository for publishing to a package repository (typically npm) as a library?

LinusBorg commented 5 years ago

All of this can be implemented with a plugin.

Plus I think the whole app structure needs to stay (just moved, maybe - to /example) since every lib needs some sort of demo to test live anyway.

kazupon commented 5 years ago

I think that's need to consider bundler. In general, the library author also needs to be concerned about the code size to be bundled. vue-cli can currently only be supported with webpack. we cannot bundle with rollup.

LinusBorg commented 5 years ago

Yeah I agree. Roll up is usually better suited to bundle smaller libraries.

I'm actually experimenting with roll up in a vue-cli project right now and plan to turn it into a cli plugin over the holidays if it works out well.

kestred commented 5 years ago

Definitely, I've used / had-success-with rollup in the past--- do either of you have particular thoughts about how a rollup option might be superior to the current Vue CLI Service's vue-cli-service build --target lib?

Mostly smaller code-size output?

LinusBorg commented 5 years ago

That would be mostly it, yes. Plus the ability to create a module that uses actual ESModule exports (esm format).

From what I have tried so far, usually the vue-cli "app" becomes an example/demo application that I use to the the lib I write - for this, the dev server setup etc is still great. Also the test plugins etc are still 100% useful.

It's just the lib code that I would bundle with rollup.

kazupon commented 5 years ago

@LinusBorg

I'm actually experimenting with roll up in a vue-cli project right now and plan to turn it into a cli plugin over the holidays if it works out well.

Have you already published the code on GitHub repo? I'm interested in your experimental code due to need to setup my project. :)

LinusBorg commented 5 years ago

Edit:

I misread. I didn't get much done for the roll up plugin, but started a similar one that's focussed on setting up the project folder for building a lib/plugin.

Can share later, even though it's not fully working yet and not documented.

If you're more intersted in rollup, have a look at the setup I used for bulding portal-vue 2.0.0 (unreleased) here: https://github.com/LinusBorg/portal-vue/tree/next

kazupon commented 5 years ago

Thank you very much! I'll try to check your project.

chriszrc commented 5 years ago

Not sure if this is the best issue to add to, but I tried using the cli support for building a library project for the first time, and found the whole experience to be awful. I'm not sure if changing that experience is a matter of better documentation or, as @kestred proposed, a better scaffold for library projects, but either way, I think there needs to be improvement here.

I was trying to build a library so that I could have a place to reuse components between several related vue projects. The first thing I wanted to do was have more than one component be accessible from the library. The next thing I wanted was an easy way to use the library locally, without having to publish either to npm or even a remote git repo. However, any of those options appear to require changes to the default generated project (changes to package.json for instance, a main entry, etc), and even after following the one tutorial I found online:

https://medium.com/justfrontendthings/how-to-create-and-publish-your-own-vuejs-component-library-on-npm-using-vue-cli-28e60943eed3

I still ran into errors trying to actually use the exported components from my library. I'm sure if I were better versed in the nuances of module formats and package creation maybe I could get it work, but that's kinda the point. I think it should be easy for any user to come along and at least have the generated library work with a cli generated project-

kazupon commented 5 years ago

I had made MVP of Vue CLI plugin. The documentation is WIP, but you can try it. https://github.com/kazupon/vue-cli-plugin-p11n

As motivation, this Vue CLI plugin is making for my project (next vue-i18n) scaffolding, if you would like to feedback, I'll try to improve my Vue CLI plugin.

@kestred In my opinion, it's not necessary to support with Vue CLI itself, beause we can realize with Vue CLI plugin.

gatherben commented 5 years ago

I'd like to echo @chriszrc comment, i just spent the weekend banging my head trying to get the cli's library output to work properly, and it was awful. I followed the same tutorial he came across, managing to get it to work properly with ES based projects, but couldn't get TS based project to work to save my life. I honestly can't tell if the library build target is fully functional or if i'm doing something wrong.

Luckily I found this issue and switched to using @kazupon 's plugin which made everything sooooo much easier. So thanks for that @kazupon ! There are a few issue with it right now, but overall it was a much easier experience, and I'd like to see something similar implemented in the CLI. If it's another plugin I think that's 100% fine in my book, but I feel like we should have an official option of some sort available for users starting library projects.

yaquawa commented 4 years ago

Any progress on this? came from https://github.com/vuejs/vue-cli/issues/1081

vuejs / vue-cli