Looking for the Vue.js counterpart? Check out the Nuxt.js starter.
A starter to create your slice library with Next.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!
- 📣 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 React Documentation, to learn more about Prismic with React
Here's a step-by-step tutorial to get started using this starter.
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-next
$ cd slice-library-starter-next
$ 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.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.
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: 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.
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.js is the slice component itself.
Slices behave just like any regular Next.js component but receives a slice prop containing its slice fields. You can install additional dependencies to the project like Tailwind CSS or Theme UI, although you might need to update the Storybook configuration and stories to reflect those.
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 8888 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 loginand$ yarn prismic sm --bootstrapagain.
For comprehensive documentation about using the Slice Builder check the dedicated documentation.
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~
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.
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 select "Other" under "Framework Preset", expand the "Build and Output Settings" options and set "Output Directory" to out. You can then 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.
Congratulations! You documentation is now hosted and will update itself whenever you commit to your repository.
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:
- My library does not contain any non-public licensed assets
☝️ For comprehensive rules refer to the contest blog post.