drsensor / vue-authoring-template

Vue project template for authoring component and their use case

vue-authoring-template

_{Click one of this badge for more info}

---

This template is to help authoring Vue component with it's use case in story-scenario (storybook) format.

vue init DrSensor/vue-authoring-template

In case you need to convince your Lead Dev to give you permission open-sourcing your work :

"Authoring component and publish it to npm for later use can help reduce complexity ^{by delegating the work of finding bug and adding feature} of big/long-running project _{to the community}"

Motivation

1. There is a time when developer involved in a project then build component to solve specific problem 😎
2. One day this developer happen to do the same thing again in different project with slight alteration 😏
3. Then doing it again, and again, and again 😫
4. Now this developer have build many component with the same topic 😂
5. So, why not publish it as a single component with that one topic in mind to npm? 😲
6. However, the component must be showcased in mvce style to make it easy to understand and maintainable 😖
7. As the time passed, he/she is to lazy to do that because no template/config/cli/whatever for authoring the component in that way 💩

Features

• Write your storybook story-scenario (a.k.a use case) in .vue single-file-component format, not .js or .jsx
• Option to generate circleci config to:
  • publish vue component to npm and unpkg _{(need to git push --tags)}
  • deploy storybook page to surge.sh
  • evaluate pull-requests and temporarily deploy storybook page to <name><#PR_number>.surge.sh _{(auto teardown when PR is merged)}
• Choose pre-installed and configured storybook addon:
  • knobs
  • actions
  • docs related addon:
    • readme
    • notes
• Order the story and scenario alphabetically or manually re-order using Array|Object in src/stories/config.js
• Auto generate README.md

Usage

vue init DrSensor/vue-authoring-template

After that, you can:

• start in development mode

npm run dev # or
yarn dev

• deploy storybook page directly to http://surge.sh

npm run deploy # or
yarn deploy

• publish component directly to http://npmjs.com

# see https://docs.npmjs.com/getting-started/semantic-versioning#semver-for-publishers
npm version [patch|minor|major]
npm publish

• build vue component

# the output will be in dist/
npm run build:component # or
yarn build:component

• build the storybook page

# the output will be in .storybook/dist/
npm run build:storybook # or
yarn build:storybook

Project Structure

.
├── package.json
├── .bilirc                 // choose and configure the component you want to package in here
├── .editorconfig
├── .gitignore
│
├── .circleci
│   └── config.yml
│
├── .storybook              // storybook related config
│   ├── addons.js
│   ├── config.js
│   └── webpack.config.js
│
└── src
    ├── components              // place 1 or more components to author here
    │   └── HelloWorld.vue
    │
    ├── mixins                  // if needed, reduce complexity by separating any long code as mixins
    │   ├── mix1.js
    │   └── mix2.js
    │
    └── stories                 // use-case/usage of the component written in story-scenario analogy
        ├── Story1
        │   └── Scenario1.vue
        ├── Story2
        ├── Story3
        ├── config.js           // config to re-order the story and the scenario
        └── index.js            // chain and add the addon here

Looking for suggestion!

• How to customize style of the storybook
• Authoring Vuex module? Is it necessary?
• any others?

Support

See CONTRIBUTING.md for contributing directly via:

• Pull Requests or
• Create Issues

License

MIT License

---

Modify/clone/fork/do-anything to this template and generated README and any others content as you wish.

vue-authoring-template's Issues

Add support for publising to CDN

I happen to had a project that need to load component at runtime. Some way to do that is to use Async Component. To do that I need to build my component and save it in local disk or build it as UMD to be able to served in https://unpkg.com when publishing to npm. Luckily, poi support build component as UMD by

poi build --format umd --dist dist/umd

Reference:

• https://github.com/InCuca/vue-standalone-component/blob/master/template/package.json

Option for adding specific storybook addon for only in specific scenario and/or story

Currently, chaining addon was global by specifying it in src/stories/index.js. This way is too cluttered because index.js consists codes not only for chaining addon. To make it better, I plan to separate it into a different file in src/stories/addon-chain.js. For adding addon only for specific scenario/story we can use object-literal-lookups, so:

in src/stories/addon-chain.js

import Footer from '~/Footer.md'
import Readme from '~/README.md'

export default {
   Story1: {
      Senario1: (story, scenario) => withNotes(scenario.__notes || '')(story)
   },
   Story2: function (story) {
         let docsStory = withReadme(Readme)(story)
         return withFooter(Footer)(docsStory)
   },
   default: (story, scenario) => withDocs(scenario.__docs || '')(story)
}

and in src/stories/index.js

.
.
if (chainAddon[storyName][scenarioName] instanceof Function) {
   var addAddon = chainAddon[storyName][scenarioName]
} else if (chainAddon[storyName] instanceof Function) {
   var addAddon = chainAddon[storyName]
} else addAddon = chainAddon['default']

let storyWithAddons = addAddon(story, Component)

Stories.add(scenarioName, storyWithAddons)

Add option to deploy to github pages

Because storybook-deployer not working as I expected (I guess the problems is in poi-preset-storybook),
I'm thinking of alternatives for using:

• gh-pages-spa - need to generate 404.html and edit .storybook/dist/index.html after build.
• vue-gh-pages - I doubt it work with storybook but at least I have alternative

Rearrange file code into src folder

Why? Take a look at this

Yes, components/ and stories/ separated by node_modules. This is why most of Vue project template that are not related to config are placed in src/. So there is need to rearrange to be like

project_root
│
.
.
└── src
│   ├── components/
.   ├── mixins/
.   ├── stories/
    └── utils/

Add option for authoring Vuex module

For authoring Vuex module there is kind of usage like:

• 1 page, many components
• multiple pages, multiple/single components on each page

To support that usage, in storybook implementation its need:

• Vue-router to support multiple pages
• Vue mixins to reduce many declarations of ...map{Vuex}

Vue Mixins

I also think of this template not also publishing vuex-modules but also vue-mixins that consist ...map{vuex} declarations. Something like:

mixins/mymodule.js

export default {
  computed: {
    ...mapGetters('mymodule', ['status', 'itemName'])
  },
  methods: {
     ...mapActions('mymodule', ['add', 'delete'])
  }
}

then in scenario use it like

<script>
import mymoduleMix from '../mixins/mymodule'
export default {
  mixins: [mymoduleMix]
}
</script>

Project Structure

When authoring vuex modules, the project structure need to support multiple .vue file in one scenario.

---

vue_router = false
-> 1 page, many components

Scenario1/
├── Component1.vue
├── Component2.vue
└── Layout.vue                // this is where Component1 and Component2 being use

---

vue_router = true
-> add addon storybook-router
-> multiple pages, multiple/single components on each page

Scenario1/
├── Layout1.vue
├── Layout2
│   ├── Component1.vue
│   ├── Component2.vue
│   └── Layout.vue
├── App.vue
└── routes.js

---

click 👍 if you agree!

👇

Better support of storybook addon info

@DrSensor commented on Thu Jan 11 2018

Replace storybook/addon-info with storybook-vue-addon-info until the official one support Vue.

Change to yeoman for scaffolding

Because vue init was deprecated in exchange of vue invoke with purpose to inject config, file, and other stuff, its preferable to use yeoman for scaffolding. Also yeoman has desktop app for it and can be integrated to IDE so that will benefit some windows user that use visual studio or webstorm. And also its more testable than vue init. For injecting maybe if I have a time and there is a need for it, I will create vue-cli-plugin for injecting storybook config and file.

Better support utilizing @storybook/addon-action in Vue

Use global mixin or extend to make action can be called like this.$action(label, payload).
For example:

Vue.mixin({
  methods: {
    $action (label, payload) {
      this.$emit('action', label, payload)
    }
  }
})

and in render function on stories/index.js

render () {
    return <story onAction={action(`${storyName}/${componentName}`)} />
}

"One for All" packaging

Package vue component as:

• umd
• cjs
• esm

And publish it to:

• NPM
• CDN:
  • unpkg
  • jsdelivr

If this enhancement use bili, then poi might be removed because the original purpose of poi is to bundle vue component as library. This also open the possibility to use official storybook cli and addon without any quirk. And maybe it can solve #1 and able add support publishing to github pages.

In package.json, use fields:
main for cjs
module for es
unpkg and jsdelivr for minified umd until webpack prioritize module over browser.

Support 2 CDN (https://unpkg.com and https://jsdelivr.com) in case one of them is server down.

use vue-cli 3.0 way when it's ready

This issue for anticipating vue-cli 3.0.

Currently, this template using poi because vue build was removed. Poi is great for scaffolding project and hide the configuration project in prebuilt poi-presets. However, it's also not really copas friendly because it uses webpack-chain format for extending webpack configuration while many webpack-loader and storybook-addon in their README use curly brackets format and that make some user confused how to add that addon/loader. To make it copy-paste friendly, need to introduce config.merge(curlyBracketConfig) in the .storybook/poi.config.js.

Take for example storybook-readme, if this template use webpack config of storybook then the user will know where to put storybookBaseConfig to apply that addon.

need to keep on track poi-preset-storybook with storybook default config. Create commit change bot maybe...

Use CI for automatic testing

this issue can be solved when [email protected] is ready

Before writing the CI script, first:

1. Create dummy repo on github
2. Get surge token and npm token
3. Setup build that dummy repo and fill the Environment Variables setting

The CI flow will be

1. git clone ... the dummy repo
2. vue create DrSensor/vue-authoring-template ... to the folder of cloned dummy repo
3. git add -u . add and update un-staged change and file
4. git commit --amend --no-edit rewrite the latest commit
5. npm version patch patch version to be able to published to npm
6. git push --force --tags force push code and all tags

Workaround before [email protected]
Use expect to skip prompt.

Add functional component option

PENDING: Need someone to review and/or give a vote about this feature.

In case someone need to build component that able to sparing 500 ms, on average, with 10000 rendered elements.

Add option for packaging multiple component as plugins

Ability to generate vue file plugin in src/index.js for storing multiple components in src/components/*.vue like in many Vue UI framework.

Reference

to many in 😂

1. https://alligator.io/vuejs/creating-custom-plugins/ - Tips: loop through components folder and use require('${name}').default