Mtillmann / shoplifter

compact, asset-related, oauthless, esm, shopify api client

Shoplifter - Simple Shopify Asset Helper

This helper is intended to work with cli scripts that manage assets and script_tags of a shopify instance and its theme.

Prerequisites

Tokens and Credentials

You'll need a SHOPIFY_ACCESS_TOKEN from your shopify instance. This can be acquired by creating an app inside shopify, then to be further described here...

Apart from the SHOPIFY_ACCESS_TOKEN you'll need a THEME_ID if you plan to manage assets, your MYSHOPIFY_DOMAIN and the API_VERSION (2022-04 may be used as a fallback).

The MYSHOPIFY_DOMAIN should is the subdomain of your instance, between https:// and .myshopify.com, i.e. https://THATS_YOUR_MYSHOPIFY_DOMAIN.myshopify.com

The THEME_ID can be found in the URL when you manage or view the theme settings: .../themes/THAT_NUMBER_HERE.

The latest API_VERSION can be looked up in the shopify documentation, although 2022_04 is a safe default since that's what this client is built on.

env vars

The credentials are passed as environment variables. During your build process you should pass them as repository secrets (GitHub) or something similar.

During development, you can pass them by using a .env file in the root of your project:

SHOPIFY_ACCESS_TOKEN=shpat_SOME_HASH
THEME_ID=123456789012
MYSHOPIFY_DOMAIN=averycoolshop
API_VERSION=2022-04

Make sure to echo .env >> .gitignore

Usage

CLI

After installing (npm i Mtillmann/shoplifter --save) the package, add a new command to your project's package.json:

{
  //...
  "scripts": {
    //...
    "shoplifter": "shoplifter"
    // key may be whatever, value part is fixed
  }
}

This enables you to call the helper like this:

npm run shoplifter -- asset:get

Make sure you use the -- between the npm call and the arguments, otherwise the arguments will be passed to npm, not to the shoplifter binary!

Alternatively you can create a specific command in your package.json like this:

{
  //...
  "scripts": {
    //...
    "upload-some-asset": "shoplifter asset:put assets/some-script.js dist/some-script.js"
  }
}

Calling the script requires no further arguments and inside the script definition there is no need for the --.

npm rum upload-some-asset

Programmatic

Import the class you need, then call the class' methods with the same signature as the CLI arguments (see below):

import {Asset} from 'shoplifter';

//assuming you have properly set the env vars (see above)

//await variant
const assetList = await new Asset().get();

//promise variante
new Asset().get().then(resp => {
    //...
});

//emitter callback variant
//this should only be used during development. 
//the callback allows for inspection of certain responses
//without interupting internal calls
(new Asset(resp => {
    console.log(resp)
})).get();

// if you have no environment vars, you can set the properties like so:

let asset = new Asset();
asset.SHOPIFY_ACCESS_TOKEN = '...';
asset.MYSHOPIFY_DOMAIN = '...';
asset.THEME_ID = '...';
asset.API_VERSION = '...';

// then proceed as usual

API

Asset

Assets are files inside themes.

the THEME_ID env var controls inside which theme the files are manipulated

asset:put / new Asset().put()

Creates or updates an asset on the remote.

argument	description
destination	The destination file, i.e. assets/some-file.ext
source	Source content. If the argument looks like a filename, the client will attempt to read it from disk, otherwise the string content is used

npm run shoplifter -- asset:put assets/some-script.js dist/some-script.js

new Asset().put('assets/some-script.js', 'dist/some-script.js');

asset:get / new Asset().get()

Fetches a list or assets or single asset when key (filename) is given.

argument	description
key (optional)	when given, only the asset that matches the given key aka filename will be returned

npm run shoplifter -- asset:get

new Asset().get();

npm run shoplifter -- asset:get assets/some-script.js

new Asset().get('assets/some-script.js');

asset:delete / new Asset().delete()

Deletes an asset on the remote by given filename.

argument	description
key	remote filename of the asset to delete

npm run shoplifter -- asset:delete assets/some-script.js

new Asset().delete('assets/some-script.js');

ScriptTag

changes on script_tags may take several seconds until they appear in the frontend

script_tags exist outside of themes. All src-properties passed must be publicly accessible

after an asset update you must also update (put) an existing script_tag because the public url of the asset will have changed!

tag:get / new ScriptTag().get()

argument	description
id (optional)	when given, only the script tag with the given id will be returned

npm run shoplifter -- tag:get

new ScriptTag.get();

npm run shoplifter -- tag:get 123456789

new ScriptTag.get(123456789);

tag:post / new ScriptTag().post()

Creates a new script_tag.

argument	description
src	file to be used inside script tag. If given URI does not begin with http, it is assumed that it's an "asset key", which is then fetched to acquire the public_url of the asset.
--event=onload (optional)	set the event property of the script tag
--cache=false (optional)	set the cache property of the script tag
--display_scope=online_store (optional)	set the display_scope property of the script tag

npm run shoplifter -- tag:post assets/some-script.js

new ScriptTag().post('assets/some-script.js'/*, ... */);

tag:put / new ScriptTag().put()

Updates an existing script_tag.

argument	description
src	see above in post
id	either the numeric script tag id OR 'auto' to find and update the existing script tag that points to the given src

optional arguments are identical to the post method's arguments.

npm run shoplifter -- tag:put assets/some-script.js 123455678
npm run shoplifter -- tag:put assets/some-script.js auto

new ScriptTag().put('assets/some-script.js', 123455678/*, ... */);
new ScriptTag().put('assets/some-script.js', 'auto'/*, ... */);

tag:upsert / new ScriptTag().upsert()

Updates or creates a script_tag for the given asset.

argument	description
src	see above in post

optional arguments are identical to the post method's arguments.

npm run shoplifter -- tag:upsert assets/some-script.js

new ScriptTag().upsert('assets/some-script.js'/*, ... */);

tag:count / new ScriptTag().count()

Fetches script_tag-count from remote.

npm run shoplifter -- tag:count

new ScriptTag().count();

tag:delete / new ScriptTag().delete()

Deletes a script_tag by given id.

npm run shoplifter -- tag:delete 12345678812

new ScriptTag().delete(1234567232);

tag:deleteforfile / new ScriptTag().deleteforfile()

Deletes a script_tag for a given filename that's matched inside the remote script_tag's src-attr. Use with caution.

npm run shoplifter -- tag:deleteforfile assets/some-script.js

new ScriptTag().deleteforfile("assets/some-script.js");

tag:find / new ScriptTag().find()

Finds a list of script_tags by given filename`.

npm run shoplifter -- tag:find assets/some-script.js

new ScriptTag().find("assets/some-script.js");

tag:findid / new ScriptTag().findid()

Yields the id of first remote script_tag whose src-attr matches given filename. Primarily used internally...

npm run shoplifter -- tag:findid assets/some-script.js

new ScriptTag().findid("assets/some-script.js");