A minimalistic framework for demonstrating your Vue components, inspired by react-storybook.
- Getting Started
- Writing Scenarios
- Component Shorthand
- Additional Component Properties
- Component Injection
- Showcase
- Development
- License
Install it:
cd my-project
npm install --save-dev vue-play vue-play-cli
# vue-play-cli gives you the `vue-play` command
# vue-play is the UI utils.
Add npm scripts:
{
"scripts": {
"play": "vue-play start",
"play:build": "vue-play build"
}
}
Write play entry
to load your examples:
// ./play/index.js
import {play} from 'vue-play'
import MyButton from './components/MyButton.vue'
play('Button', module)
.add('with text', h => h(MyButton, 'hello'))
.add('with emoji', h => h(MyButton, '๐ซ'))
Then just run npm run play
and go to http://localhost:5000
For more usages on vue-play-cli, please head to vue-play/vue-play-cli.
The hard way
There're two pages in your play app, one is the app interface which has a sidebar and it can toggle scenarios of your components, the other page is for rendering the examples, this page will be loaded as iframe in app interface.
And only the latter needs to load scenarios that you write in the play entry
, let's say ./play/index.js
:
import {play} from 'vue-play'
import MyButton from './MyButton.vue'
play('MyButton', module)
.add('with text', h => h(MyButton, ['text']))
// ./play/app.js
import app from 'vue-play/dist/app'
import 'vue-play/dist/app.css'
// bootstrap app
app()
// ./play/preview.js
import preview from 'vue-play/dist/preview'
// loads the scenarios at ./play/index.js
import scenarios from './'
// actually render the scenarios in preview page
// when the preview page is ready
// it will tell the app interface what scenarios we have
preview(scenarios)
Add app interface
and preview
to your webpack entry:
module.exports = {
// ...
entry: {
app: './play/app.js',
preview: './play/preview.js'
},
// don't forget to generate html output for both of them
plugins: [
new HtmlWebpackPlugin({
filename: 'index.html',
chunks: ['app']
}),
new HtmlWebpackPlugin({
filename: 'preview.html',
chunks: ['preview']
})
]
}
That's it, you're all set!
scenario
, a.k.a. story in react-storybook, it's usually an example for demostrating your real component.
You can keep scenarios anywhere you want, for example you can keep them all at ./play/index.js
, you can also use separate files for them, or even name them *.play.js
in your component directory and load them dynamically.
import { play } from 'vue-play'
import MyButton from '../src/components/MyButton.vue'
// Use `play` to describe component title
// use .add to add scenario for that component
play('MyButton', module)
.add('with text', h => h(MyButton, ['hello world']))
.add('with emoji', h => h(MyButton, ['๐๐ป']))
We can use Webpack's require.context to load modules dynamically.
import { configure } from 'vue-play'
const load = requireContext => requireContext.keys().map(requireContext)
const scenarios = load(require.context('../src/components', true, /.play.js$/))
configure(scenarios, module)
If you are using render function you won't need to register components, you only need this when you are using the template property:
// ./play/index.js
import MyButton from './MyButton.vue'
// these components will be registered globally
module.exports.components = {
MyButton
}
play('MyButton', module)
.add('with text', {
template: '<my-button>text</my-button>'
})
You can also put the example component in a seperate file, like .vue
file and register components there, locally.
import MyButton from './MyButton.vue'
// assuming MyButton.name is 'my-button'
play(MyButton, module)
// MyButton will be automatially registered in scenarios
// so you don't have to use module.exports.components = {MyButton}
.add('with text', '<my-button></my-button>')
// then the app sidebar will look like:
// - my-button
// - with text
To customize the displayName
in sidebar and the componentName
which is used to register itself in scenarios, you can simply set them in your component:
<!-- ./MyButton.vue -->
<script>
export default {
name: 'my-other-button',
displayName: 'Show off my cute button'
}
</script>
Or use methods:
play(MyButton, module)
.name('my-other-button')
.displayName('Show off my cute button')
.add('with text', '<my-other-button>text</my-other-button>')
If you only need template
or render
property for your component, you can use component shorthand
, which means you can directly set the value of scenario to a template string or render function:
import Example from './Example.vue'
play('Button', module)
.add('template shorthand', '<my-button>text</my-button>')
.add('render function shorthand', h => h(MyButton, ['text']))
.add('full component', {
data() {},
methods: {},
render(h) {}
// ...
}).
.add('single file', Example)
note: If you are using template
shorthand, you should use Vue standalone build as well.
The component for each scenario is a typical Vue component, but it can also accept some additional properties for documenting its usage, eg:
play('Button', module)
.add('with text', {
// a valid vue component
...component,
// additional
example,
// ...
})
Type: string
The example code of your component.
Type: HTML string
Optionally display a readme tab to show detailed usage.
Log data to app console.
Feel free to add your projects here:
# run example play script
npm run play
# build vue-play
# you don't need this when developing
npm run build