npm i slater -g
A new toolkit for building and deploying themes on Shopify.
This project is an active work in progress!
The CLI for compiling and uploading themes is stable, but the starter theme needs some love!
Want to help? We'd love to have you. Ideas, feedback, critiques ๐ shoot us an Issue.
- asset pipeline via Webpack, Babel, PostCSS/SASS
- built-in deployment tool
- live reloading
- simple config
- easy integration into existing themes
- starter theme (WIP)
- Quick Start
- Usage
- Command Line
- Deployment
- Live Reloading
- Guides and Tutorials
- Slater in the Wild
- Contributors
- License
The easist way to get started with Slater is slater init
. init
outputs a
default folder structure into the directory of your choice.
slater init <root>
Don't forget to install the dependencies.
npm install
You'll need to define one or more themes in the provided slater.config.js
file
to deploy to, similar to a standard Shopify config.yml
file.
module.exports = {
themes: {
development: {
id: '12345...',
password: 'abcde...',
store: 'store-name.myshopify.com',
ignore: [
'settings_data.json'
]
}
}
}
Then, from the project root:
slater watch
And that's it! Slater will watch your local theme for changes and sync them to your remote site when they update ๐.
Slater makes some assumptions out of the box, but it can be easily customized to fit most existing projects.
Slater projects require themes to be defined in the
slater.config.js
.
By default it looks for a theme called development
:
module.exports = {
themes: {
development: { ... }
}
}
You can call it whatever you want though.
module.exports = {
themes: {
dev: { ... }
}
}
Just be sure to specify your theme name on the CLI:
slater build --theme dev
You can also define as many themes as you like. Use these for a production theme, staging, or whatever you like.
module.exports = {
themes: {
dev: { ... },
test: { ... },
live: { ... }
}
}
Each of these themes should have its own theme id
value. Theme IDs can be
found by going to Online Store > Themes > Customize Theme and plucking the ID
from the URL i.e. ../admin/themes/<id>/editor
.
All themes can use the same password
property. To get one, create your own
private
app
and pull it from there. Make sure your private app allows for read/write to the
"Theme templates and theme assets".
All theme files should be located within a single source directory. By default,
Slater looks for a /src
directory in your project root.
To adjust this, specify an in
prop on your config:
module.exports = {
in: '/source'
}
Files within this directory will be built and copied to /build
in
your project root, and then synced to your remote theme.
To adjust your local build directory, specify an out
prop on your config:
module.exports = {
out: '/dist'
}
Slater uses Webpack internally to compile a single JavaScript entry point. By
default, it looks for /src/scripts/index.js
.
You can specify a different entry point using the assets
object on your
config:
module.exports = {
assets: {
in: '/src/scripts/index.js'
}
}
Slater uses PostCSS by default. It's configured to allow SASS-like nesting, in addition to all modern CSS goodies.
To compile your styles, simply import your root stylesheet into your JavaScript entrypoint:
import '../styles.css'
// rest of your project scripts
You can also use SASS. Simple specify the sass
preset in your assets config:
module.exports = {
in: '/src/scripts/index.js'
assets: {
presets: [
'sass'
]
}
}
To make your JavaScript a little easier to work with, Slater supports alias definitions and environment variables.
module.exports = {
assets: {
in: '/src/scripts/index.js'
alias: {
components: './src/scripts/components'
},
env: {
API_KEY: JSON.stringify('abcde'),
}
},
themes: {
// ...
}
}
Which you can then use in your JavaScript like this:
import api from 'components/api.js'
const fetcher = api({
key: API_KEY
})
For convenience, there's also a built-in alias @
that points to the directory
containing your JavaScript entry point.
N.B. Keep in mind, these environment variables are public, so don't use them for any secret keys, passwords, or any value that you need to keep private! Also, these values are passed directly to Webpack's Define Plugin, so please refer to those docs for clarity.
Watches for file changes and syncs updates to your specified theme.
slater watch
Compiles assets and copies all files from the config.in
directory to the
config.out
directory.
slater build
Sync local files or directories to your remote theme. A direct interface to
[@slater/sync], which @slater/cli
uses internally.
slater sync build/snippets/hero.liquid # file
slater sync build/snippets # directory
slater sync # defaults to config.out
Any of the core commands can be combined with the following options:
--config <path>
- specify the path to your config file--theme <name>
- specify a named theme from your config file
To deploy a theme, combine the above commands as needed:
slater build && slater sync --theme production
slater
uses an local SSL certification to correspond with Shopify's HTTPS
hosted themes. To take advantage of live-reloading, you need to create a
security exception for the slater
cert (this is safe). To do this, load
https://localhost:3000 in your browser, and follow
the instructions for adding an exception. If it works, you should see this in
your browser window:
slater running
Adding Slater to any existing Theme
The following sites were built using some version of Slater. Send us a PR to add to this list!
Slater uses lerna to manage the monorepo. That makes developing locally pretty simple, but a little different from what you might be used to. Use the steps below to get up and running locally:
- Clone this repository
- From the project root, install core dependencies with
npm i
- From the project root, run
npm run bootstrap
- Define a
packages/theme/test.config.js
file with your Slater config data - Use the
test
specific commands in/theme/package.json
to run your local theme - Make neat, granular commits
- Be descriptive
- Reference open/closed issues where applicable
- Open a pull request!
Important: don't increment any of the core package versions. The core Slater team will handle versioning when publishing to npm.
![]() Eric Bailey ๐ป ๐ ๐ ๐ง | ![]() Kevin Green ๐ป ๐ ๐ ๐ง | Joe Refoy ๐ ๐ป ๐ง | Ward Penney ๐ ๐ | Tomasz Bujnowicz ๐ ๐ป | Sean Orfila ๐ฌ | antonio ๐ ๐ |
dana kim ๐ค | kotte ๐ป ๐จ ๐ค |
MIT License ยฉ The Couch