Slice Library Nuxt.js Starter

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
- Creating a Slice
- Launching the Slice Builder
🚀 Deploying Your Storybook
- Hosting on Netlify
- Hosting on Vercel
☑️ Submission Checklist

📚 Useful Links

📣 Contest Announcement Blog Post, check rules and additional information there!
🌐 Contest Forum Section, get help and share feedback here~
🔪 Slice Machine Documentation, to learn more about Slice Machine
📖 Prismic Vue.js Documentation, to learn more about Prismic with Vue.js

🏁 Getting Started

Here's a step-by-step tutorial to get started using this starter.

Setting up Your Project

Start by forking this repository, this will create a copy of this repository on your GitHub account.

Once the repository is forked, you can clone it locally and install its dependencies:

$ git clone https://github.com/<your_username>/slice-library-starter-nuxt
$ cd slice-library-starter-nuxt
$ 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~

Using the Prismic CLI

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.3-beta.0 or greater:

# Installing the CLI globally using Yarn (optional)
$ yarn global add prismic-cli@3.8.3-beta.0
# Installing the CLI globally using npm (optional)
$ npm install --global prismic-cli@3.8.3-beta.0

# 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.

Setting up Prismic and Slice Machine

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-storybook

This 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! (although you might want to stick with version 5.x.x of those addons because Slice Machine installs version 2.2.2 of @nuxtjs/storybook to prevent some issues) Here's an example of a more elaborated Storybook documentation of a slice library for inspiration: sms-hoy-storybook.netlify.app

⚠ 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, should fix the issue.

Well done! You are now ready to start developing your slice library with Slice Machine.

👩‍💻 Developing

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.

Creating a Slice

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.

Launching the Slice Builder

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 --develop

This 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, 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 login and $ yarn prismic sm --bootstrap again.

For comprehensive documentation about using the Slice Builder check the dedicated documentation.

🚀 Deploying Your Storybook

One of the requirements of this contest if to have your Storybook documentation 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 once, no need to have it at multiple location, so just pick one that works for you~

Hosting on Netlify

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 last build options step every default should be good. We already took care of configuring the build command and publish directory through a netlify.toml file. 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.

Hosting on Vercel

To host your Storybook documentation on Vercel go to: vercel.com/import.

Once on the page click "Continue" under "Import Git Repository", you might need to create an account or to log in if not already. After you logged in, paste the GitHub repository URL you worked on in the dedicated field and click "Continue", Vercel might ask for access to your account.

On the last build options step every default should be good and Nuxt.js should have already been selected. We already took care of configuring everything to deploy your documentation. Click "Deploy" 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.