Installation
In any usage of Lunchbox, the first step is to install the package and ThreeJS:
npm install lunchboxjs three
Next steps depend on your workflow:
Lunchbox-Only Apps
Then create and mount your app just like Vue. The only difference is you import createApp
from lunchboxjs
, not vue
:
import { createApp } from 'lunchboxjs'
import App from './App.vue'
const app = createApp(App)
app.mount('#app')
From there, you can write in Vue single file components (SFCs) or however else you write your Vue apps. (We'll be writing the rest of these docs in SFCs.)
Nuxt 3
To use Lunchbox with Nuxt 3, create a file in your plugins
directory called lunchbox.client.ts
(or lunchbox.client.js
if you're using JS) and paste the following:
import { lunchbox } from 'lunchboxjs'
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(lunchbox)
})
This installs the Lunchbox Vue plugin. From there, follow the steps below in the HTML Apps component section.
Vue Apps
Plugin
⭐ New as of version 0.2.1019 (Nov 2022)! ⭐
Use the lunchbox
plugin (included in the lunchboxjs
package) to create a Lunchbox app inside a standard HTML app.
// Example Vite setup
import { createApp } from 'vue'
import { lunchbox } from 'lunchboxjs'
import App from './App.vue'
createApp(App).use(lunchbox).mount('#app')
Component
Then, in your App.vue
component:
<template>
<h1>My Lunchbox App</h1>
<lunchbox :root="LunchboxApp" />
<!-- ...etc... -->
</template>
<script setup>
import LunchboxApp from './LunchboxApp.vue'
</script>
Then, in your LunchboxApp.vue
component:
<template>
<lunchbox>
<mesh>
<boxGeometry />
<!-- etc... -->
</mesh>
</lunchbox>
</template>
More options
Any props that the wrapper component recognizes can be used on the HTML component:
<template>
<lunchbox :root="LunchboxApp" background="transparent" ortho />
</template>
<script setup>
import LunchboxApp from './LunchboxApp.vue'
</script>
Along with a root
prop, you can also set an appSetup
prop to further modify the app. appSetup
accepts one argument, the Lunchbox app, and must return the app:
<template>
<lunchbox :root="LunchboxApp" :appSetup="appSetup" />
</template>
<script setup>
import LunchboxApp from './LunchboxApp.vue'
const appSetup = (app) => {
// add plugins, components, and any other app-level info here
// example:
app.use(myPlugin)
app.component(myComponent)
app.provide(myProvide)
// remember to return `app`!
return app
}
</script>
Or you can provide an app
prop to use an already-created (but not mounted) Lunchbox app:
<template>
<lunchbox :app="lunchboxApp" />
</template>
<script setup>
import { createApp } from 'lunchboxjs'
import LunchboxApp from './LunchboxApp.vue'
const lunchboxApp = createApp(LunchboxApp)
// you can add plugins, etc here - for example:
lunchboxApp.use(myPlugin)
lunchboxApp.component(myComponent)
lunchboxApp.provide(myProvide)
</script>
Alternative methods
You can also use a Lunchbox app in an HTML page with an iframe, or render Vue apps separately and mount the Lunchbox app in the HTML app:
// Example Vite setup
import { createApp } from 'vue'
import { createApp as createLunchboxApp } from 'lunchboxjs'
import App from './App.vue'
import LunchboxApp from './LunchboxApp.vue'
// html app
const app = createApp(App)
app.mount('#app')
// lunchbox app
const lunchboxApp = createLunchboxApp(LunchboxApp)
// assuming there's an element with ID `lunchbox` in your HTML app
lunchboxApp.mount('#lunchbox')
The latter method is what the lunchbox
plugin does under the hood, along with some additional provide/inject management.
Notes
Note that this is a more roundabout creation method than a standard Vue component/plugin because Lunchbox is a full custom renderer, and mixing renderers in Vue 3 is something the Vue community is still working on - see here for more information.