Looking for the React counterpart? Check out the Next.js starter.
A starter to create your slice library with Nuxt.js and Slice Machine for #SliceContest. This document is here to help you through the whole process of creating your library but is not comprehensive to what you can do, unleash your creativity!
- 📚 Useful Links
- 🏁 Getting Started
- 👩💻 Developing
- 🚀 Deploying Your Storybook and Website
- ☑️ Submission Checklist
- 📣 Contest Announcement Blog Post, check rules and additional information there! (starting soon 👀)
- 🌐 Contest Forum Section, get help and share feedback here~
- 📖 Prismic Nuxt.js Documentation, to learn more about Prismic with Vue.js
- 🔪 Slice Builder Documentation for Nuxt.js, to learn more about the Slice Builder
Here's a step-by-step tutorial to get started using this starter.
Start by using this repository as a template, this will create a copy of this repository on your GitHub account under a name of your choice.
Once the repository is created, you can clone it locally and install its dependencies:
$ git clone https://github.com/<your_username>/<your_repository_name>
$ cd <your_repository_name>
$ yarn install # if you use npm: `$ npm install`While your package manager installs the dependencies, you can already update the LICENSE file to replace <copyright holders> with your name. You can also update the package.json file to fill the author field~
For convenience and to be sure you are running the correct version of Prismic CLI it has been installed as part of devDependencies and aliased to the prismic script in this project. Thanks to that you can run the CLI as a package script:
# Using Yarn
$ yarn prismic <command> <options>
# Using npm
$ npm run prismic -- <command> <options>If you still wish to use the CLI installed globally make sure you are running version 3.8.5 or greater:
# Installing the CLI globally using Yarn (optional)
$ yarn global add prismic-cli@3.8.5
# Installing the CLI globally using npm (optional)
$ npm install --global prismic-cli@3.8.5
# You can then use the CLI globally...
$ prismic <command> <options>In the following sections only the Yarn version from above (recommended) will be used in the examples for the sake of simplicity.
If you do not own a Prismic account yet you can create one for free here or by using the CLI:
$ yarn prismic signup
# The CLI will then guide you through the process...Once you have a Prismic account, or if you already had one, log in within the CLI:
$ yarn prismic login
# The CLI will then guide you through the process...When logged in, you can then bootstrap your Slice Machine project, this will create you a Prismic repository for this project:
$ yarn prismic sm --bootstrap
# The CLI will then prompt you for a Prismic repository name...Finally, and since that's a requirement for this contest, you will want to bootstrap a Storybook project. Thankfully Slice Machine comes with a handy command for that:
$ yarn prismic sm --add-storybookThis should create a simple Storybook inside your project. Bear in mind though that this one is still quite basic, feel free to go fancy by adding addons and more! Here's an example of a more elaborated Storybook documentation of a slice library for inspiration: pxlsls-story.samuelhorn.com
⚠ Storybook is known for being quite picky with its dependencies. If you experience a blank page when running it with a lot of errors in the browser console try deleting your lock file and installing dependencies again, this should fix the issue.
Well done! You are now ready to start developing your slice library with Slice Machine.
Some quick reminders to help you developing your library with Slice Machine and the Slice Builder. Please refer to the documentation if you are looking for more in-depth knowledge.
To create a slice run:
$ yarn prismic sm --create-slice
# The CLI will then guide you through the process...This will create a new directory inside ./slices named after the provided slice name. Inside it index.vue is the slice component itself.
Slices behave just like any regular Nuxt.js component but receives a slice prop containing its slice fields. They are run in a Nuxt context meaning that any configuration / module you add to your nuxt.config.js file will reflect as expected on those. For example, if you want to use Tailwind CSS, its setup remains exactly the same with @nuxtjs/tailwindcss.
For comprehensive documentation about creating your own slices check the dedicated documentation.
To launch the Slice Builder you need to run 2 terminals: one for Storybook, one for the Slice Builder itself.
# On a first terminal
$ yarn storybook # or with npm: `$ npm run storybook`
# On the second terminal
$ yarn prismic sm --developThis will launch Storybook on port 3003 and the Slice Builder on port 9999, you can open a third terminal to create slices from or launch other commands...
ℹ We are aware that it will be more convenient to launch Storybook and the Slice Builder with a single command and are working on it~
⚠ Storybook is known for being quite picky with its dependencies. If you experience a blank page when running it with a lot of errors in the browser console try deleting your lock file and installing dependencies again, this should fix the issue.
⚠ We noticed that in some rare case you can get stuck in a
401 [Unauthorized]loop prompting you to log in when running the Slice Machine develop command. If this happens to you check if your Prismic repository was created, if not, try running$ yarn prismic loginand$ yarn prismic sm --bootstrapagain.
For comprehensive documentation about using the Slice Builder check the dedicated documentation.
Once you are done developing your slice library (or in between!) you can start creating your showcase website. This part should involve little to no code!
First make sure you pushed all your slices to Prismic and that you added them to the default "page" custom type.
You can then create a new document, give it the UID of home (this starter is configured to use home as the index / URL). From here you're free to compose your showcase website within the writing room using your very slices! You're also more than welcome to go further, by adding a header and a footer for example!
One of the requirements of this contest if to have your Storybook documentation and showcase website both hosted somewhere.
If you are not familiar with hosting no worries! We recommend to either use Netlify or Vercel and have done most of the setup for you already!
You only need to host the documentation and showcase website once. There's no need to have them at multiple location so just pick an hosting platform that works for you~
To host your Storybook documentation on Netlify go to: app.netlify.com/start, you might need to create an account or to log in if not already.
Once on the page click "GitHub". After granting access to your account you should now be able to see a list of your repositories. Pick the one you worked on.
On the build options step, scroll down to "Basic build settings" and set your "Build command" to be yarn build-storybook, then proceed to set the "Publish directory" right under to storybook-static. Once done, click "Deploy site" and wait for the magic to happen.
Once the build is finished, head over to the "Site overview" tab. The URL of the hosted documentation should be available at the top left of the tab (if Netlify is still building it will display you the build status instead). You can customize it by changing the site name under the "Site settings" tab.
Congratulations! You documentation is now hosted and will update itself whenever you commit to your repository.
Now to host your showcase website repeat the above steps another time, but at the build option step set instead your "Build command" to be yarn generate and your "Publish directory" to be dist. Click "Deploy site", wait another few minutes and you should be good to go!
To host your Storybook documentation on Vercel go to: vercel.com/new.
Once on the page you might need to create an account or to log in if not already using the "Continue with GitHub" button. Once done you should see an "Import Git Repository" section, from there browse your repositories to pick the one you worked on and click "Import". On the following screen just pick your personal account or a team you want to work in and hit "Select".
On the build options, step select "Other" under "Framework Preset", expand the "Build and Output Settings" options and set your "Build command" to be yarn build-storybook, then proceed to set the "Output directory" right under to storybook-static. Once done, click "Deploy site" and wait for the magic to happen.
Once the build is finished and successful, you should be redirected to a success page. The URL of the hosted documentation should be available through the "Visit" button. You can customize it by changing the site name under the "Settings" tab of the new site dashboard.
Congratulations! You documentation is now hosted and will update itself whenever you commit to your repository.
Now, to host your showcase website, repeat the above steps another time. At the build option step just pick another project name (as you just claimed <your_repository_name>) and set your "Framework Preset" to Nuxt.js. Click "Deploy site", wait another few minutes and you should be good to go!
To keep track of your progress and to be sure not to miss anything here's a simple checklist you can use. Once everything ticks you should be ready to submit your library to us by tagging @prismicio with #SliceContest on Twitter.
- My library contains at least 5 different slices
- I have updated the LICENSE to credit myself for my library
- The Storybook documentation is hosted here:
- The showcase website is fun and hosted here:
- My library does not contain any non-public licensed assets
☝️ For comprehensive rules refer to the contest blog post.