@syncify/cli 0.1.3-beta → 0.2.0-beta
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cjs.js +176 -147
- package/dist/cli.js +7 -2
- package/package.json +60 -35
- package/pnpm-lock.yaml +1493 -1461
- package/readme.md +464 -182
- package/types/api.d.ts +2 -2
- package/types/cli.d.ts +46 -42
- package/types/config/index.d.ts +18 -12
- package/types/config/terser.d.ts +267 -0
- package/types/config/views.d.ts +13 -5
- package/types/index.d.ts +13 -9
- package/types/{misc → internal}/commands.d.ts +16 -28
- package/types/{bundle → internal}/file.d.ts +87 -30
- package/types/internal/filters.d.ts +81 -0
- package/types/{bundle → internal}/hot.d.ts +14 -4
- package/types/internal/index.d.ts +509 -0
- package/types/{bundle → internal}/plugin.d.ts +7 -5
- package/types/internal/processors.d.ts +54 -0
- package/types/{misc/modes.d.ts → internal/reports.d.ts} +57 -6
- package/types/{misc → internal}/requests.d.ts +5 -4
- package/types/{misc → internal}/shared.d.ts +6 -10
- package/types/modules/html-minifier-terser.d.ts +211 -0
- package/types/transforms/image.d.ts +1 -1
- package/types/transforms/script.d.ts +191 -57
- package/types/transforms/style.d.ts +51 -10
- package/types/transforms/svg.d.ts +1 -1
- package/types/bundle/index.d.ts +0 -479
- package/types/config/minify.d.ts +0 -115
- /package/types/{bundle → internal}/cache.d.ts +0 -0
- /package/types/{misc → internal}/errors.d.ts +0 -0
- /package/types/{misc → internal}/markdown.d.ts +0 -0
package/readme.md
CHANGED
@@ -2,48 +2,53 @@
|
|
2
2
|
|
3
3
|
<hr>
|
4
4
|
|
5
|
-
#
|
5
|
+
# SYNCIFY
|
6
6
|
|
7
|
-
A lightening fast, extensible and superior alternative Shopify CLI (
|
7
|
+
A lightening fast, extensible and superior alternative Shopify CLI (Theme Development) tool. Syncify provides developers with a powerful CLI and employs an intuitive approach for creating Shopify themes.
|
8
8
|
|
9
|
-
**Syncify
|
9
|
+
**Syncify will exist as part of the [Liquify](https://liquify.dev) project**
|
10
10
|
|
11
11
|
### Key Features
|
12
12
|
|
13
|
-
- Watch, upload, download and export multiple storefronts and themes.
|
13
|
+
- Watch, upload, download and export to multiple storefronts and themes.
|
14
14
|
- Intelligent path mapping capabilities for custom directory structures.
|
15
15
|
- HOT reloading of assets, section, snippets, templates and layouts.
|
16
16
|
- Clear, concise, informative and beautiful CLI logging.
|
17
17
|
- An elegant global directory based metafields sync approach using JSON files.
|
18
18
|
- Digests and spawns existing build tools for asset transformations.
|
19
|
-
- Exposed Plugin API for adding those seeking extensibility.
|
20
19
|
- Prompt based CLI/TUI and exposed module API for script usage.
|
21
20
|
- Pull, push and merge support for aligning local and remote sources.
|
22
|
-
- Files, Pages and Redirects
|
21
|
+
- Supports additional resources like Files, Pages and Redirects.
|
23
22
|
|
24
23
|
### Why?
|
25
24
|
|
26
|
-
I have been working on the Shopify platform for
|
25
|
+
I have been working on the Shopify platform for several years and nothing the Shopify team have produced has actually increased my productivity. Despite the advancements Shopify has made in recent years I still find that their developer tooling to be rather average. The Shopify CLI is cool and all but for theme development it fails to achieve fluidity.
|
26
|
+
|
27
|
+
Syncify is how I believe theme creation, development and maintenance should be handled. It's fast, flexible, extensible, scalable and will not lock you into some restrictive low grade elementary workflow. It allows you to progressively enhance your development process and produce the most efficient and performant results with the tools you already love.
|
27
28
|
|
28
29
|
# Install
|
29
30
|
|
30
|
-
|
31
|
+
Syncify is distributed as both an ESM and CJS module. It is recommended that you install as a development dependency in your project opposed to installing globally.
|
31
32
|
|
32
33
|
**PNPM**
|
33
34
|
|
34
|
-
```
|
35
|
+
```bash
|
35
36
|
pnpm add @syncify/cli -D
|
36
37
|
```
|
37
38
|
|
39
|
+
> Use `pnpx @syncify/cli` for remote execution
|
40
|
+
|
38
41
|
**NPM**
|
39
42
|
|
40
|
-
```
|
43
|
+
```bash
|
41
44
|
npm i @syncify/cli --save-dev
|
42
45
|
```
|
43
46
|
|
47
|
+
> Use `npx @syncify/cli` for remote execution
|
48
|
+
|
44
49
|
**Yarn**
|
45
50
|
|
46
|
-
```
|
51
|
+
```bash
|
47
52
|
yarn add @syncify/cli --dev
|
48
53
|
```
|
49
54
|
|
@@ -61,15 +66,11 @@ Syncify exposes and introduces an elegant low-level method for interfacing with
|
|
61
66
|
|
62
67
|
### Asset Files
|
63
68
|
|
64
|
-
Syncify does not want to re-create or impede on developer preferences and tool appropriation. Build tools and bundlers specifically designed for processing different asset types can be spawned and run in parallel with Syncify's `build` and `watch` instances, but for more advanced use cases, Syncify also provides developers with pre-processor capabilities via
|
65
|
-
|
66
|
-
### Plugins
|
67
|
-
|
68
|
-
Syncify can be extended with Plugins. Similar to build tools like webpack and rollup, Syncify exposes a plugin API which allows you to hook into the build cycle and apply transforms to assets and files.
|
69
|
+
Syncify does not want to re-create or impede on developer preferences and tool appropriation. Build tools and bundlers specifically designed for processing different asset types can be spawned and run in parallel with Syncify's `build` and `watch` instances, but for more advanced use cases, Syncify also provides developers with pre-processor capabilities via [transforms](#transform). Transform can be leveraged for processing TypeScript, JavaScript, CSS, SCSS and SVG file types by exposing integrated configuration wrappers around popular and performant modules like ESBuild, SASS Dart, SVGO Tailwind and more!
|
69
70
|
|
70
71
|
# Setup
|
71
72
|
|
72
|
-
After installing you will need to configure a connection to your shopify store. Syncify requires you provide either an
|
73
|
+
After installing you will need to configure a connection to your shopify store. Syncify requires you provide either an Admin API Access Token (recommended) or API Key and Secret as credentials.
|
73
74
|
|
74
75
|
<details>
|
75
76
|
<summary>
|
@@ -213,6 +214,8 @@ Syncify supports `syncify.config.js` and `package.json` configurations. Dependin
|
|
213
214
|
|
214
215
|
### Default Options
|
215
216
|
|
217
|
+
This is defaults used in a `syncify.config.js` file. Options commented out within [transforms](#transform), [processors](#processors) and [minify](#minify) require peer dependencies to be installed to be used.
|
218
|
+
|
216
219
|
<!-- prettier-ignore -->
|
217
220
|
```ts
|
218
221
|
import { defineConfig } from '@syncify/syncify';
|
@@ -232,6 +235,7 @@ export default defineConfig({
|
|
232
235
|
],
|
233
236
|
hot: {
|
234
237
|
label: 'visible',
|
238
|
+
history: true,
|
235
239
|
method: 'hot',
|
236
240
|
inject: true,
|
237
241
|
scroll: 'preserved',
|
@@ -295,13 +299,53 @@ export default defineConfig({
|
|
295
299
|
],
|
296
300
|
}
|
297
301
|
},
|
298
|
-
|
302
|
+
transforms: {
|
303
|
+
script: {},
|
304
|
+
style: {},
|
305
|
+
svg: {}
|
306
|
+
},
|
307
|
+
processors: {
|
308
|
+
json: {
|
309
|
+
crlf: false,
|
310
|
+
indent: 2,
|
311
|
+
useTab: false,
|
312
|
+
exclude: []
|
313
|
+
},
|
314
|
+
// esbuild: {},
|
315
|
+
// sass: {},
|
316
|
+
// postcss: [],
|
317
|
+
// tailwind: {},
|
318
|
+
// svgo: {},
|
319
|
+
// sprite: {},
|
320
|
+
// sharp: {},
|
321
|
+
},
|
322
|
+
minify: {
|
323
|
+
json: {
|
324
|
+
assets: true,
|
325
|
+
config: true,
|
326
|
+
locales: true,
|
327
|
+
metafields: true,
|
328
|
+
templates: true,
|
329
|
+
exclude: []
|
330
|
+
},
|
331
|
+
views: {
|
332
|
+
collapseWhitespace: true,
|
333
|
+
minifySchema: true,
|
334
|
+
minifyScript: true,
|
335
|
+
minifyStyle: true,
|
336
|
+
removeComments: true,
|
337
|
+
stripDashes: true,
|
338
|
+
exclude: []
|
339
|
+
},
|
340
|
+
// script: {},
|
341
|
+
// style: {},
|
342
|
+
}
|
299
343
|
});
|
300
344
|
```
|
301
345
|
|
302
346
|
# Getting Started
|
303
347
|
|
304
|
-
It is relatively easy to get started developing Shopify themes using Syncify. If you are converting an existing project and using Theme Kit or another build environment you can progressively adapt it into your workflow by manually configuring how Syncify should behave. Whatever the case, have a look at the [
|
348
|
+
It is relatively easy to get started developing Shopify themes using Syncify. If you are converting an existing project and using Theme Kit or another build environment you can progressively adapt it into your workflow by manually configuring how Syncify should behave. Whatever the case, have a look at the [Syncify Examples](#) repository.
|
305
349
|
|
306
350
|
### Pre-requisites
|
307
351
|
|
@@ -321,11 +365,11 @@ Before going over the features Syncify provides, it is assumed that you have don
|
|
321
365
|
- [Views](#views)
|
322
366
|
- [Transforms](#views)
|
323
367
|
- [Processors](#views)
|
324
|
-
- [
|
368
|
+
- [Terser](#views)
|
325
369
|
|
326
370
|
## Directories
|
327
371
|
|
328
|
-
In Syncify you define custom base directories for your theme files. The values you define
|
372
|
+
In Syncify you define custom base directories for your theme files. The values you define refer to a directory name which is relative to the root of your project. You **cannot** define multi-level directories (eg: `some/dir`) or reverse paths (eg: `../dir`).
|
329
373
|
|
330
374
|
<!-- prettier-ignore -->
|
331
375
|
<table>
|
@@ -369,13 +413,13 @@ In Syncify you define custom base directories for your theme files. The values y
|
|
369
413
|
|
370
414
|
### Input > Output
|
371
415
|
|
372
|
-
Syncify expects projects to have an **input** directory path which contains theme **source** files. Files contained within an input directory are written to your defined **output** directory path. The generated output will be reflective of your online store and in most cases you will add the output directory to your `.gitignore` file because it can rebuilt from input.
|
416
|
+
Syncify expects projects to have an **input** directory path which contains theme **source** files. Files contained within an input directory are written to your defined **output** directory path. The generated output will be reflective of your online store and in most cases you will add the output directory to your `.gitignore` file because it can always be rebuilt from input.
|
373
417
|
|
374
418
|
If you are used to working from a single directory (e.g: Dawn) then it is important that you understand the difference between the **input** and **output** directories.
|
375
419
|
|
376
420
|
# Stores (Required)
|
377
421
|
|
378
|
-
The `stores` option accepts an **object** or **array** type. Each item will hold a
|
422
|
+
The `stores` option accepts an **object** or **array** type. Each item will hold a _settings_ object that contains references to your shopify store/s and their theme/s. For each store you define, Syncify requires you provide the shop name and theme id/s you wish to sync. The `themes` object uses a **key** > **value** structure.
|
379
423
|
|
380
424
|
> Please see theme [commands](#commands) example for more information on how this is used with the CLI.
|
381
425
|
|
@@ -388,7 +432,7 @@ The `stores` option accepts an **object** or **array** type. Each item will hold
|
|
388
432
|
### API
|
389
433
|
|
390
434
|
```ts
|
391
|
-
import { defineConfig } from '@syncify/
|
435
|
+
import { defineConfig } from '@syncify/cli';
|
392
436
|
|
393
437
|
export default defineConfig({
|
394
438
|
stores: [
|
@@ -411,7 +455,7 @@ export default defineConfig({
|
|
411
455
|
</summary>
|
412
456
|
<p>
|
413
457
|
|
414
|
-
The `domain` option expects a string value, which is your Shopify store name without the `myshopify.com` portion. The domain will be used by the CLI as a target
|
458
|
+
The `domain` option expects a string value, which is your Shopify store name without the `myshopify.com` portion. The domain will be used by the CLI as a target argument. Each store (domain) can have multiple themes.
|
415
459
|
|
416
460
|
</p>
|
417
461
|
</details>
|
@@ -422,13 +466,15 @@ The `domain` option expects a string value, which is your Shopify store name wit
|
|
422
466
|
</summary>
|
423
467
|
<p>
|
424
468
|
|
425
|
-
The `themes` option refers to theme ids the store contains. This option is an object type which uses **key** > **value** mappings. The theme **keys** represent a unique target name, this can be any alpha numeric value. The **key** value
|
469
|
+
The `themes` option refers to theme ids the store contains. This option is an object type which uses **key** > **value** mappings. The theme **keys** represent a unique target name, this can be any alpha numeric value. The **key** value is used by the CLI as target reference. The **value** should be the theme id.
|
426
470
|
|
427
471
|
</p>
|
428
472
|
</details>
|
429
473
|
|
430
474
|
# Metafields
|
431
475
|
|
476
|
+
###### NOT YET AVAILABLE
|
477
|
+
|
432
478
|
The `metafields` directory `path` reference is where you can provide **global** JSON metafield files that can be synced to your Shopify store. Metafield sync capabilities provided by Syncify use a simple **directory** > **file** based approach. The sub-directory names represent a metafield `namespace` value and JSON file names contained within represent metafield `key` values.
|
433
479
|
|
434
480
|
> Syncify will keep your remote and local metafield references aligned with one another and warn you when local versions do not match remote versions. This will help prevent you from overwriting changes that may have been applied by third-party apps or online within your store.
|
@@ -438,7 +484,7 @@ The `metafields` directory `path` reference is where you can provide **global**
|
|
438
484
|
Syncify provides you with simple interactive prompt based approach for importing pre-existing metafields from your online store. You can optionally choose which metafields you'd like to maintain. Use the `-m` or `--metafields` flag together with the `--pull` flag on the command line to download metafields:
|
439
485
|
|
440
486
|
```
|
441
|
-
$ syncify
|
487
|
+
$ syncify --metafields --pull
|
442
488
|
```
|
443
489
|
|
444
490
|
**Merge Metafields**
|
@@ -446,7 +492,7 @@ $ syncify -m --pull
|
|
446
492
|
Working with metafields from your local machine may have result in unexpected overwrites if changes were made to remote versions that conflict with local versions. In order to combat this Syncify support **merge** capabilities which can be used to merge changes when metafield modification timestamps differ. Use the `-m` or `--metafields` flag together with the `--merge` flag on the command line perform local and remote alignments.
|
447
493
|
|
448
494
|
```
|
449
|
-
$ syncify
|
495
|
+
$ syncify --metafields --merge
|
450
496
|
```
|
451
497
|
|
452
498
|
**Structure**
|
@@ -589,11 +635,13 @@ The `metafields` option refers to a directory within your project which can cont
|
|
589
635
|
|
590
636
|
# Paths
|
591
637
|
|
592
|
-
The `paths` option allows you to define a custom set of path locations which point to theme specific files contained within the defined `input` directory. Syncify does not require you set a development structure consistent with that required by Shopify
|
638
|
+
The `paths` option allows you to define a custom set of path locations which point to theme specific files contained within the defined `input` directory. Syncify does not require you set a development structure consistent with that required by Shopify and you should begin to decouple from that logic as it is generally a flawed and borderline daft approach. The contents (files) contained within your **input** will be re-routed as a standard theme structure that Shopify understands when generating **output** distribution.
|
639
|
+
|
640
|
+
Each path option accepts either a `string` or `string[]` array list of glob [anymatch](https://www.npmjs.com/package/anymatch) patterns. Paths will automatically resolve to the `input` directory, so you do not need to include it within your configurations.
|
593
641
|
|
594
642
|
### API
|
595
643
|
|
596
|
-
By default, Syncify assumes you are using the basic-bitch (default) structure as
|
644
|
+
By default, Syncify assumes you are using the basic-bitch (default) structure as follows:
|
597
645
|
|
598
646
|
<!-- prettier-ignore -->
|
599
647
|
```ts
|
@@ -620,7 +668,7 @@ export default defineConfig({
|
|
620
668
|
|
621
669
|
### Custom Structures
|
622
670
|
|
623
|
-
Below are **2** different **input** structures and an **output** structure. The **default structure** is what Syncify will use (as above) if no `paths` have been defined in your configuration, the tool defaults to this. The **customized structure** is an example of how you _could_ arrange an `input` directory using the Syncify `paths` option. The **output structure** is what Syncify will generated as an **output** which Shopify
|
671
|
+
Below are **2** different **input** structures and an **output** structure. The **default structure** is what Syncify will use (as above) if no `paths` have been defined in your configuration, the tool defaults to this. The **customized structure** is an example of how you _could_ arrange an `input` directory using the Syncify `paths` option. The **output structure** is what Syncify will generated as an **output** which Shopify can digest.
|
624
672
|
|
625
673
|
<table>
|
626
674
|
<thead>
|
@@ -713,7 +761,7 @@ Below are **2** different **input** structures and an **output** structure. The
|
|
713
761
|
</tbody>
|
714
762
|
</table>
|
715
763
|
|
716
|
-
There is no distributed difference between the **default** and **customized** structures illustrated above. Both would generate an **output** that Shopify understands, requires and reasons with. Only the **input** source locations differ. The **output** Syncify creates will always be written to a standard Shopify theme structure regardless of how you may decide to organize **input** paths.
|
764
|
+
There is no distributed difference between the **default** and **customized** structures illustrated above. Both would generate an **output** that Shopify understands, requires and reasons with. Only the **input** source locations differ. The **output** Syncify creates will always be written to a standard Shopify theme structure regardless of how you may decide to organize **input** paths. Custom structures give you creative freedom and does not impose a restrictive workflow you may have become behest to working with Dawn and the Shopify CLI. Welcome to the better approach, you're welcome.
|
717
765
|
|
718
766
|
### Options
|
719
767
|
|
@@ -819,7 +867,9 @@ An array list of glob path patterns to `.json` or `.liquid` **template** files.
|
|
819
867
|
|
820
868
|
# HOT
|
821
869
|
|
822
|
-
Live reloading is supported in watch mode. Syncify leverages websocket's, XHR and statically served endpoints to provide this capability with zero configuration or the need to install or setup additional tooling. No extensions and no complexities. When you invoke `--hot` syncify will listen for messages sent via websocket on the client and carry out HOT replacements of Assets, Sections, Snippets, Layouts and Templates without triggering full-page refreshes.
|
870
|
+
Live reloading is supported in watch mode. Syncify leverages websocket's, XHR and statically served endpoints to provide this capability with zero configuration or the need to install or setup additional tooling. No extensions and no complexities. When you invoke `--hot` syncify will listen for messages sent via websocket on the client and carry out HOT replacements of Assets, Sections, Snippets, Layouts and Templates without triggering full-page refreshes.
|
871
|
+
|
872
|
+
> The HOT reload approach Syncify employs tends to be considerably faster than HOT reloading with the Shopify CLI.
|
823
873
|
|
824
874
|
### Assets
|
825
875
|
|
@@ -835,13 +885,15 @@ In order to provide HOT replacements Syncify employs a mild form of DOM hydratio
|
|
835
885
|
|
836
886
|
# Spawn
|
837
887
|
|
838
|
-
The spawn option accepts a **key** > **value** list of commands (
|
888
|
+
The spawn option accepts a **key** > **value** list of commands (i.e: scripts) which can be used when running in **watch** (`--watch`) or **build** (`--build`) modes. The Spawn configuration option allows you to leverage additional build tools and have them execute in parallel with Syncify as child processes.
|
889
|
+
|
890
|
+
Spawned processes allow you use your preferred asset bundlers such as [Rollup](#), [Webpack](#), [Gulp](#) and many more without having to run multiple npm-scripts.
|
839
891
|
|
840
892
|
### Overview
|
841
893
|
|
842
894
|
There are 2 available modes from which you can trigger a spawned process. When a process is spawned in `watch` mode it will run along side Syncify in parallel and execute sequentially in the order of which each spawn is defined. You need to provide any --flags your command (build tool or bundler) requires when running. Spawning a process in `build` mode will trigger spawned commands only 1 time, so it is here where you would provide the compile-only or build-only command, ie: not using watch flags/arguments.
|
843
895
|
|
844
|
-
The Syncify **build** mode re-builds the entire theme and you might choose to run this mode using the Syncify `--prod` flag, if you require context of the environment, mode or action taking place within spawned config files, then take a look at the available [Utilities](#utilities) Syncify exposes to help
|
896
|
+
The Syncify **build** mode re-builds the entire theme and you might choose to run this mode using the Syncify `--prod` flag, if you require context of the environment, mode or action taking place within spawned config files, then take a look at the available [Utilities](#utilities) which Syncify exposes to help conditionally load plugins or trigger different build types in accordance with the Syncify execution cycle.
|
845
897
|
|
846
898
|
### CLI
|
847
899
|
|
@@ -849,13 +901,16 @@ The Syncify **build** mode re-builds the entire theme and you might choose to ru
|
|
849
901
|
--spawn, -s <name> # spawn targeting
|
850
902
|
```
|
851
903
|
|
852
|
-
###
|
904
|
+
### Configuration
|
853
905
|
|
854
906
|
<!-- prettier-ignore -->
|
855
907
|
```ts
|
856
908
|
import { defineConfig } from '@syncify/syncify';
|
857
909
|
|
858
910
|
export default defineConfig({
|
911
|
+
|
912
|
+
// ...
|
913
|
+
|
859
914
|
spawn: {
|
860
915
|
build: {},
|
861
916
|
watch: {}
|
@@ -866,11 +921,13 @@ export default defineConfig({
|
|
866
921
|
|
867
922
|
## Usage
|
868
923
|
|
869
|
-
In most situations you will leverage the spawn option to compile TypeScript or JavaScript
|
924
|
+
In most situations you will leverage the spawn option to compile something like TypeScript or JavaScript but it is important to note that this capability is not specific to these assets types. Syncify is using [cross-spawn](https://www.npmjs.com/package/cross-spawn) under the hood to help negate any cross-platform issues that may arise. Below are a couple examples where we spawn up 2 well known JavaScript bundlers and lastly we illustrate how to spawn multiple processes.
|
925
|
+
|
926
|
+
> All stdout/stderr/stdio from spawned processes will be piped through and intercepted by Syncify, which might result in output being stripped of color.
|
870
927
|
|
871
928
|
### Rollup Example
|
872
929
|
|
873
|
-
If you are processing JavaScript asset files using the [Rollup](https://rollupjs.org/) bundler you can spawn build and watch processes by providing the rollup commands to each mode accordingly. Rollup is a fantastic choice for handling `.js` files
|
930
|
+
If you are processing JavaScript asset files using the [Rollup](https://rollupjs.org/) bundler you can spawn build and watch processes by providing the rollup commands to each mode accordingly. Rollup is a fantastic choice for handling `.js` files. In this example, it is assumed that a `rollup.config.js` file is located in the root of your project.
|
874
931
|
|
875
932
|
<!-- prettier-ignore -->
|
876
933
|
```ts
|
@@ -941,7 +998,9 @@ export default defineConfig({
|
|
941
998
|
|
942
999
|
# Transform
|
943
1000
|
|
944
|
-
In Syncify, asset files can be transformed
|
1001
|
+
In Syncify, asset files can be transformed before being written to the defined `output` directory and uploaded to your Shopify store. The `transform` option provides users with control of the "asset pipeline" and Syncify exposes configuration wrappers for handling files together with modern developer tooling.
|
1002
|
+
|
1003
|
+
Syncify supports built-in and partial processing for the following file types:
|
945
1004
|
|
946
1005
|
- `.json`
|
947
1006
|
- `.js`
|
@@ -955,23 +1014,106 @@ In Syncify, asset files can be transformed and augmented before being written to
|
|
955
1014
|
|
956
1015
|
## Scripts
|
957
1016
|
|
958
|
-
Syncify exposes a `
|
1017
|
+
Syncify exposes a `script` transform option which supports TypeScript (`.ts` and `.tsx`) and/or JavaScript (`.js` and `.jsx`) bundling using [ESBuild](https://esbuild.github.io/). Script transforms use a pre-defined set of processing configurations and will produce lean JavaScript bundles designed to work seamlessly in development mode or when leveraging HOT reloads. Syncify will also apply refinements to distribution bundles focused on performance when generating production builds for your Shopify theme.
|
1018
|
+
|
1019
|
+
> ESBuild is the same bundler used under the hood by tools like [vite](https://vitejs.dev/) and [tsup](https://tsup.egoist.sh). If you are using existing tools like Webpack or Rollup, consider adopting ESBuild as its a far superior option.
|
1020
|
+
|
1021
|
+
### Installing ESBuild
|
1022
|
+
|
1023
|
+
In order for you to leverage **script** transforms, you will need to install ESBuild as a development dependency. Syncify will complain if you try to use script options without esbuild installed.
|
1024
|
+
|
1025
|
+
```bash
|
1026
|
+
pnpm add esbuild -D
|
1027
|
+
```
|
1028
|
+
|
1029
|
+
### Bundling TypeScript
|
1030
|
+
|
1031
|
+
The **script** transform option aims to make bundling easy but also extensible for more advanced use cases. Syncify will automatically detect `tsconfig.json` (or `jsconfig.json`) files located in your workspace and respect processing options defined within. By default, Syncify will produce **ESM** module formats that output in **ES2016** but you can also generate **IIFE** bundles and even inline code as a snippets within `<script></script>` tags.
|
1032
|
+
|
1033
|
+
The `script` options accepts several different structures and it is up to you how you wish to provide settings. The below code sample depicts the default configuration structure:
|
1034
|
+
|
1035
|
+
<!--prettier-ignore-->
|
1036
|
+
```ts
|
1037
|
+
import { defineConfig } from '@syncify/syncify';
|
1038
|
+
|
1039
|
+
export default defineConfig({
|
1040
|
+
transforms: {
|
1041
|
+
script: [
|
1042
|
+
{
|
1043
|
+
input: [],
|
1044
|
+
format: 'esm',
|
1045
|
+
target: 'es2016',
|
1046
|
+
snippet: false,
|
1047
|
+
rename: '',
|
1048
|
+
external: [],
|
1049
|
+
watch: [],
|
1050
|
+
esbuild: {}
|
1051
|
+
}
|
1052
|
+
]
|
1053
|
+
}
|
1054
|
+
})
|
1055
|
+
```
|
1056
|
+
|
1057
|
+
You may prefer to use rename (entry point) structures instead. When we are using rename entry points the prefix path expects either `snippets/` or `assets/` be provided. When passing `snippets/` then a snippet will be generated, whereas `assets/` will generate a `.js` file.
|
1058
|
+
|
1059
|
+
> Rename entry points accept `[file]`, `[dir]` and `[ext]` placeholders.
|
1060
|
+
|
1061
|
+
<!--prettier-ignore-->
|
1062
|
+
```ts
|
1063
|
+
import { defineConfig } from '@syncify/syncify';
|
1064
|
+
|
1065
|
+
export default defineConfig({
|
1066
|
+
transforms: {
|
1067
|
+
script: {
|
1068
|
+
|
1069
|
+
// Producing 2 inline snippet <script> bundles
|
1070
|
+
// Output will be slideshow.js.liquid and search-form.js.liquid
|
1071
|
+
'snippets/[file][ext]': [
|
1072
|
+
'scripts/sections/slideshow.ts',
|
1073
|
+
'scripts/sections/search-form.ts'
|
1074
|
+
]
|
1075
|
+
|
1076
|
+
// Producing an IIFE script as an asset
|
1077
|
+
// The return value is accessible via window.Foo
|
1078
|
+
'assets/foo.min.js': {
|
1079
|
+
input: 'scripts/index.ts',
|
1080
|
+
format: 'iife',
|
1081
|
+
globalName: 'window.Foo,
|
1082
|
+
}
|
1083
|
+
}
|
1084
|
+
}
|
1085
|
+
})
|
1086
|
+
```
|
959
1087
|
|
960
1088
|
## Styles
|
961
1089
|
|
962
|
-
|
1090
|
+
###### TAILWIND IS NOT YET SUPPORT
|
1091
|
+
|
1092
|
+
Syncify exposes a `style` transform option which can be used for CSS (`.css`) and SCSS/SASS (`.scss` or `.sass`) bundling. Style transform support is made possible by using compilers like [Dart SASS](#), [PostCSS](#) and/or [Tailwind](#). The `style` option provides developers with replicated configuration control but you may also prefer to use standard config files (e.g: `postcss.config.js`) which Syncify also supports.
|
1093
|
+
|
1094
|
+
Style transforms help alleviate the complexities sometimes involved in setting up these tools so you can easily process asset specific stylesheets or generate output as a **snippet** within `<style></style>` tags.
|
963
1095
|
|
964
1096
|
### SASS Support
|
965
1097
|
|
966
|
-
Syncify provides
|
1098
|
+
Syncify provides SCSS/SASS transform support for `.scss` and `.sass` file types using [Dart SASS](#). Using SASS required you to install the Dart module as a development dependency in your project. Syncify will complain if you try to use SASS transforms without Dart SASS installed.
|
967
1099
|
|
968
|
-
```
|
1100
|
+
```bash
|
969
1101
|
pnpm add sass -D
|
970
1102
|
```
|
971
1103
|
|
972
|
-
###
|
1104
|
+
### Tailwind Support
|
973
1105
|
|
974
|
-
|
1106
|
+
Syncify supports TailwindCSS for CSS processing. If you require transform support for Tailwind, you need to install the TailwindCSS module as a development dependency in your project. Syncify will ignore Tailwind class name occurrences without the module installed.
|
1107
|
+
|
1108
|
+
```bash
|
1109
|
+
pnpm add tailwindcss -D
|
1110
|
+
```
|
1111
|
+
|
1112
|
+
> Tailwind is not yet available in the beta.
|
1113
|
+
|
1114
|
+
### PostCSS Support
|
1115
|
+
|
1116
|
+
In addition to SASS transformation, Syncify also support CSS (post)-processing using [PostCSS](#). If you wish have Syncify handle CSS transforms then you need to install **PostCSS** as a development dependency. Syncify will complain if you try to use PostCSS transforms without PostCSS installed.
|
975
1117
|
|
976
1118
|
> Provide PostCSS plugins and any specific settings within the `postcss.config.js` file.
|
977
1119
|
|
@@ -979,7 +1121,7 @@ In addition to SASS transformation, Syncify also support CSS processing using [P
|
|
979
1121
|
pnpm add postcss -D
|
980
1122
|
```
|
981
1123
|
|
982
|
-
**Please note:** If you are using Syncify to compile SASS files, then by default the transformed CSS will be passed to PostCSS.
|
1124
|
+
**Please note:** If you are using Syncify to compile SASS files, then by default the transformed CSS will be passed to PostCSS.
|
983
1125
|
|
984
1126
|
### Usage
|
985
1127
|
|
@@ -993,15 +1135,6 @@ import { defineConfig } from '@syncify/syncify'
|
|
993
1135
|
|
994
1136
|
export default defineConfig({
|
995
1137
|
transforms: {
|
996
|
-
script: {
|
997
|
-
'assets/bundle.min.js': 'scripts/bundle.ts',
|
998
|
-
'assets/mithril.min.js': 'scripts/virtual.ts',,
|
999
|
-
'snippets/[dir]-[file]': ['scripts/globs/*.ts'],
|
1000
|
-
'assets/globs.min.js': {
|
1001
|
-
input: 'scripts/globs.ts',
|
1002
|
-
format: 'iife'
|
1003
|
-
}
|
1004
|
-
},
|
1005
1138
|
style: {
|
1006
1139
|
'assets/stylesheet.min.css': {
|
1007
1140
|
input: 'styles/stylesheet.scss',
|
@@ -1331,24 +1464,125 @@ PostCSS options
|
|
1331
1464
|
|
1332
1465
|
# Processors
|
1333
1466
|
|
1334
|
-
Syncify
|
1467
|
+
In Syncify, **processors** refer to the external tools used in [Transforms](#transform) (i.e: SVGO, ESBuild SASS etc). The `processors` configuration option provides developers a point of control for configuring these (supported) _third party_ modules. The configurations defined in processors will used as the defaults bundling options of each transform and allows developers to retain a single point of control from which all _third party_ processor operations will refer, this saves you having to include multiple external config files in your projects workspace.
|
1335
1468
|
|
1336
|
-
|
1469
|
+
<!-- prettier-ignore -->
|
1470
|
+
```ts
|
1471
|
+
import { defineConfig } from '@syncify/cli'
|
1337
1472
|
|
1338
|
-
|
1473
|
+
export default defineConfig({
|
1339
1474
|
|
1340
|
-
|
1475
|
+
// ...
|
1341
1476
|
|
1342
|
-
|
1343
|
-
|
1477
|
+
processors: {
|
1478
|
+
json: {}, // applied to json transforms
|
1479
|
+
esbuild: {}, // applied to script transforms
|
1480
|
+
sass: {}, // applied to style transforms
|
1481
|
+
postcss: [], // applied to style transforms
|
1482
|
+
tailwind: {}, // applied to style transforms
|
1483
|
+
svgo: {}, // applied to svg transforms
|
1484
|
+
sprite: {}, // applied to svg transforms
|
1485
|
+
sharp: {}, // applied to img transforms
|
1486
|
+
}
|
1487
|
+
})
|
1488
|
+
```
|
1344
1489
|
|
1345
|
-
|
1490
|
+
> Using processors requires installing the relative module you'd like to leverage. This is an opt-in capability.
|
1346
1491
|
|
1347
|
-
|
1348
|
-
|
1492
|
+
### External Config Files
|
1493
|
+
|
1494
|
+
Some third party tools allow (or require) config file usage (e.g: `postcss.config.js`, `tailwind.config.js` etc etc). Syncify will check for the existence of configuration files in the workspace and use them as the processor defaults. In situations where an external config file is detected and you've defined custom `processor` settings which differ from the Syncify defaults then options of the external config will overwritten (or merged) by those defined on `processor` configuration.
|
1495
|
+
|
1496
|
+
Say you're using a `postcss.config.js` file to provide a couple of plugins in your project, for example:
|
1497
|
+
|
1498
|
+
<!-- prettier-ignore -->
|
1499
|
+
```js
|
1500
|
+
// postcss.config.js
|
1501
|
+
|
1502
|
+
module.exports = {
|
1503
|
+
plugins: [
|
1504
|
+
require('postcss-nested')(),
|
1505
|
+
require('autoprefixer')()
|
1506
|
+
]
|
1507
|
+
};
|
1508
|
+
|
1509
|
+
```
|
1510
|
+
|
1511
|
+
Syncify will automatically detect and digest this file at runtime. It will use the export value when processing CSS with PostCSS and will consider it the **default** value, assigning it to `processors.postcss`. Instead of providing a `postcss.config.js` file, you _could_ instead just pass this to the **postcss** processor option, for example:
|
1512
|
+
|
1513
|
+
<!-- prettier-ignore -->
|
1514
|
+
```js
|
1515
|
+
// syncify.config.ts
|
1516
|
+
|
1517
|
+
import { defineConfig } from '@syncify/cli';
|
1518
|
+
|
1519
|
+
export default defineConfig({
|
1520
|
+
// ...
|
1521
|
+
processors: {
|
1522
|
+
postcss: [
|
1523
|
+
require('postcss-nested')(),
|
1524
|
+
require('autoprefixer')()
|
1525
|
+
]
|
1526
|
+
}
|
1527
|
+
});
|
1528
|
+
```
|
1529
|
+
|
1530
|
+
### Transform Overrides
|
1531
|
+
|
1532
|
+
You can overwrite processor defaults on a per-file basis at the transform level. Each transform exposes a processor property which accepts the same options which will apply an immutable merge with processor defaults. This is helpful when you require file specific transforms.
|
1533
|
+
|
1534
|
+
Take the following code sample, notice how we've passed an SASS override on certain files. In this example the `style.scss` transform will use the `processor.sass` configuration, whereas the the `example.scss` file will override the `processor.sass` defaults and use a different set of configuration options.
|
1535
|
+
|
1536
|
+
<!-- prettier-ignore -->
|
1537
|
+
```js
|
1538
|
+
// syncify.config.ts
|
1539
|
+
|
1540
|
+
import { defineConfig } from '@syncify/cli';
|
1541
|
+
|
1542
|
+
export default defineConfig({
|
1543
|
+
// ...
|
1544
|
+
processor: {
|
1545
|
+
sass: {
|
1546
|
+
sourcemap: true,
|
1547
|
+
style: 'compressed',
|
1548
|
+
include: ['node_modules/'], // the style.scss include path
|
1549
|
+
}
|
1550
|
+
},
|
1551
|
+
transform: {
|
1552
|
+
style: [
|
1553
|
+
{
|
1554
|
+
input: 'styles/style.scss',
|
1555
|
+
postcss: true
|
1556
|
+
},
|
1557
|
+
{
|
1558
|
+
input: 'styles/example.scss',
|
1559
|
+
snippet: true,
|
1560
|
+
sass: {
|
1561
|
+
style: 'expanded', // we override the output style
|
1562
|
+
include: ['some/dir'] // we override the include path
|
1563
|
+
}
|
1564
|
+
}
|
1565
|
+
]
|
1566
|
+
}
|
1567
|
+
});
|
1568
|
+
```
|
1569
|
+
|
1570
|
+
### Usage Proposition
|
1571
|
+
|
1572
|
+
Processors (and transforms) are optional in Syncify and may not fit your use case but there is an added benefit to using them. If you are leveraging HOT reloads or require different outputs be generated, then they are a great help. They also take a lot of the guess work out of bundling, so you can focus on writing code without worrying about bundler configurations.
|
1573
|
+
|
1574
|
+
[Spawn](#spawn) processes are another option available for cases where you require a different complier which is not supported by Syncify, but please note that spawned processes will not apply HOT reloads and execute in child process. Whatever the case may be, it is important you weigh up the usage proposition for your project and determine which works best for you and your development workflow.
|
1349
1575
|
|
1350
|
-
###
|
1576
|
+
### Supported Processors
|
1351
1577
|
|
1578
|
+
Syncify provides extendable support with the following build tools:
|
1579
|
+
|
1580
|
+
- [ESBuild](#esbuild)
|
1581
|
+
- [SASS](#sass)
|
1582
|
+
- [PostCSS](#postcss)
|
1583
|
+
- [Tailwind](#tailwind-support)
|
1584
|
+
- [SVGO](#svgo)
|
1585
|
+
- [Sprite](#sprite)
|
1352
1586
|
- [Sharp](#sharp)
|
1353
1587
|
|
1354
1588
|
# ESBuild
|
@@ -1357,23 +1591,23 @@ Syncify provides integrated support with ESBuild for processing TypeScript, Java
|
|
1357
1591
|
|
1358
1592
|
See also [Script Transforms](#).
|
1359
1593
|
|
1360
|
-
###
|
1594
|
+
### Using Config File
|
1361
1595
|
|
1362
|
-
|
1596
|
+
ESBuild Configuration files `esbuild.config.js` are not supported for script transforms.
|
1363
1597
|
|
1364
|
-
|
1365
|
-
pnpm add esbuild -D
|
1366
|
-
```
|
1598
|
+
### Using Processors
|
1367
1599
|
|
1368
|
-
|
1600
|
+
The `esbuild` property is were ESBuild configuration option defaults can be provided.
|
1369
1601
|
|
1370
1602
|
<!-- prettier-ignore -->
|
1371
1603
|
```ts
|
1372
|
-
{
|
1604
|
+
import { defineConfig } from '@syncify/cli'
|
1605
|
+
|
1606
|
+
export default defineConfig({
|
1373
1607
|
processors: {
|
1374
|
-
esbuild: {} //
|
1608
|
+
esbuild: {} // ESBuild Options
|
1375
1609
|
}
|
1376
|
-
}
|
1610
|
+
})
|
1377
1611
|
```
|
1378
1612
|
|
1379
1613
|
# SASS
|
@@ -1382,23 +1616,23 @@ Syncify provides integrated support with SASS Dart for processing SASS/SCSS file
|
|
1382
1616
|
|
1383
1617
|
See also [Style Transforms](#).
|
1384
1618
|
|
1385
|
-
###
|
1619
|
+
### Config File is not supported
|
1386
1620
|
|
1387
|
-
|
1621
|
+
SASS Configuration files are not supported for style transforms.
|
1388
1622
|
|
1389
|
-
|
1390
|
-
pnpm add sass -D
|
1391
|
-
```
|
1623
|
+
### Using Processors
|
1392
1624
|
|
1393
|
-
|
1625
|
+
The `sass` property is were SASS configuration option defaults can be provided.
|
1394
1626
|
|
1395
1627
|
<!-- prettier-ignore -->
|
1396
1628
|
```ts
|
1397
|
-
{
|
1629
|
+
import { defineConfig } from '@syncify/cli'
|
1630
|
+
|
1631
|
+
export default defineConfig({
|
1398
1632
|
processors: {
|
1399
|
-
sass: {} // SASS
|
1633
|
+
sass: {} // SASS Options
|
1400
1634
|
}
|
1401
|
-
}
|
1635
|
+
})
|
1402
1636
|
```
|
1403
1637
|
|
1404
1638
|
# PostCSS
|
@@ -1407,73 +1641,73 @@ Syncify provides integrated support with PostCSS for processing CSS file types.
|
|
1407
1641
|
|
1408
1642
|
See also [Style Transforms](#).
|
1409
1643
|
|
1410
|
-
###
|
1644
|
+
### Using Config File
|
1411
1645
|
|
1412
|
-
|
1646
|
+
Provide a `postcss.config.js` file in the root of your project or within the defined `config` path.
|
1413
1647
|
|
1414
|
-
|
1415
|
-
pnpm add postcss -D
|
1416
|
-
```
|
1648
|
+
### Using Processors
|
1417
1649
|
|
1418
|
-
|
1650
|
+
The `postcss` property accepts an array list of PostCSS plugins.
|
1419
1651
|
|
1420
1652
|
<!-- prettier-ignore -->
|
1421
1653
|
```ts
|
1422
|
-
{
|
1654
|
+
import { defineConfig } from '@syncify/cli'
|
1655
|
+
|
1656
|
+
export default defineConfig({
|
1423
1657
|
processors: {
|
1424
|
-
|
1658
|
+
postCSS: [] // PostCSS Plugins
|
1425
1659
|
}
|
1426
|
-
}
|
1660
|
+
})
|
1427
1661
|
```
|
1428
1662
|
|
1429
1663
|
# SVGO
|
1430
1664
|
|
1431
|
-
Syncify provides integrated support with SVGO for processing SVG file types. If you would like to produce SVG Sprites, then
|
1665
|
+
Syncify provides integrated support with SVGO for processing SVG file types. If you would like to produce SVG Sprites, then refer to [Sprites](#) section which uses SVGO under the hood.
|
1432
1666
|
|
1433
|
-
See also [SVG Transforms](#)
|
1667
|
+
See also [SVG Transforms](#).
|
1434
1668
|
|
1435
|
-
###
|
1669
|
+
### Using Config File
|
1436
1670
|
|
1437
|
-
|
1671
|
+
Provide a `svgo.config.js` file in the root of your project or within the defined `config` path.
|
1438
1672
|
|
1439
|
-
|
1440
|
-
pnpm add svgo -D
|
1441
|
-
```
|
1673
|
+
### Using Processors
|
1442
1674
|
|
1443
|
-
|
1675
|
+
The `svgo` property accepts SVGO configuration options.
|
1444
1676
|
|
1445
1677
|
<!-- prettier-ignore -->
|
1446
1678
|
```ts
|
1447
|
-
{
|
1679
|
+
import { defineConfig } from '@syncify/cli'
|
1680
|
+
|
1681
|
+
export default defineConfig({
|
1448
1682
|
processors: {
|
1449
|
-
|
1683
|
+
svgo: {} // SVGO Options
|
1450
1684
|
}
|
1451
|
-
}
|
1685
|
+
})
|
1452
1686
|
```
|
1453
1687
|
|
1454
1688
|
# Sprite
|
1455
1689
|
|
1456
|
-
Syncify provides integrated support for creating SVG Sprites using
|
1690
|
+
Syncify provides integrated support for creating SVG Sprites using [SVG Sprites](#). SVG Sprite is a low level module that optimizes SVGs and bakes them into sprites that Syncify can inline and output.
|
1457
1691
|
|
1458
|
-
See also [SVG Transforms](#)
|
1692
|
+
See also [SVG Transforms](#).
|
1459
1693
|
|
1460
|
-
###
|
1694
|
+
### Config File is not supported
|
1461
1695
|
|
1462
|
-
|
1696
|
+
SVG Sprites Configuration files are not supported for Sprite transforms.
|
1463
1697
|
|
1464
|
-
|
1465
|
-
pnpm add svg-sprites -D
|
1466
|
-
```
|
1698
|
+
### Using Processors
|
1467
1699
|
|
1468
|
-
|
1700
|
+
The `sprite` property accepts SVG Sprite configuration options.
|
1469
1701
|
|
1470
1702
|
<!-- prettier-ignore -->
|
1471
1703
|
```ts
|
1472
|
-
{
|
1704
|
+
import { defineConfig } from '@syncify/cli'
|
1705
|
+
|
1706
|
+
export default defineConfig({
|
1473
1707
|
processors: {
|
1474
|
-
sprite: {} // SVG Sprite
|
1708
|
+
sprite: {} // SVG Sprite Options
|
1475
1709
|
}
|
1476
|
-
}
|
1710
|
+
})
|
1477
1711
|
```
|
1478
1712
|
|
1479
1713
|
# Sharp
|
@@ -1482,28 +1716,83 @@ Syncify provides integrated support for convert large images in common formats t
|
|
1482
1716
|
|
1483
1717
|
See also [Image Transforms](#)
|
1484
1718
|
|
1485
|
-
###
|
1719
|
+
### Config File is not supported
|
1486
1720
|
|
1487
|
-
|
1721
|
+
Sharp Configuration files are not supported for Image transforms.
|
1488
1722
|
|
1489
|
-
|
1490
|
-
pnpm add sharp -D
|
1491
|
-
```
|
1723
|
+
### Using Processors
|
1492
1724
|
|
1493
|
-
|
1725
|
+
The `sharp` property accepts Sharp configuration options.
|
1494
1726
|
|
1495
1727
|
<!-- prettier-ignore -->
|
1496
1728
|
```ts
|
1497
|
-
{
|
1729
|
+
import { defineConfig } from '@syncify/cli'
|
1730
|
+
|
1731
|
+
export default defineConfig({
|
1498
1732
|
processors: {
|
1499
|
-
sharp: {} // Sharp
|
1733
|
+
sharp: {} // Sharp Options
|
1500
1734
|
}
|
1501
|
-
}
|
1735
|
+
})
|
1502
1736
|
```
|
1503
1737
|
|
1504
|
-
#
|
1738
|
+
# Terser
|
1739
|
+
|
1740
|
+
The **Terser** option is for minification configuration options. Syncify supports minification and compression of Liquid, HTML JSON and also provides handling around Script and Style Transform file types. Terse output is core to theme development using Syncify and developers should indeed get into a habit a distributing themes in terse a format.
|
1741
|
+
|
1742
|
+
### Does Liquid Minification Matter?
|
1743
|
+
|
1744
|
+
When we are talking about Liquid syntax specifically, there is no real measurable performance increase one gets removing whitespace and newlines but Syncify does more than just strip whitespace, it also performs code elimination. The Syncify minification process will remove comments, strip extraneous delimiter trims and where possible it replaces syntax occurrences for faster equivalents.
|
1745
|
+
|
1746
|
+
### Usage
|
1747
|
+
|
1748
|
+
Produce terse output by passing `--terse` (or `--minify`) command flag. The `--prod` flag will also produce terse output. You can pass a boolean `false` to options to skip minification.
|
1749
|
+
|
1750
|
+
### Terse Options
|
1505
1751
|
|
1506
|
-
|
1752
|
+
Below is is the default configuration Syncify uses for minification.
|
1753
|
+
|
1754
|
+
<!-- prettier-ignore -->
|
1755
|
+
```ts
|
1756
|
+
import { defineConfig } from '@syncify/cli'
|
1757
|
+
|
1758
|
+
export default defineConfig({
|
1759
|
+
terser: {
|
1760
|
+
json: {
|
1761
|
+
assets: true,
|
1762
|
+
config: true,
|
1763
|
+
locales: true,
|
1764
|
+
metafields: true,
|
1765
|
+
templates: true,
|
1766
|
+
exclude: []
|
1767
|
+
},
|
1768
|
+
view: {
|
1769
|
+
collapseWhitespace: true,
|
1770
|
+
minifySchema: true,
|
1771
|
+
minifyScript: true,
|
1772
|
+
minifyStyle: true,
|
1773
|
+
replaceSugar: true,
|
1774
|
+
removeComments: true,
|
1775
|
+
stripDashes: true,
|
1776
|
+
swapAssign: true,
|
1777
|
+
exclude: []
|
1778
|
+
},
|
1779
|
+
// Requires ESBuild to be installed
|
1780
|
+
script: {
|
1781
|
+
mangleProps: true,
|
1782
|
+
keepNames: false,
|
1783
|
+
legalComments: true,
|
1784
|
+
keepNames: false,
|
1785
|
+
legalComments: "inline",
|
1786
|
+
mangleProps: undefined,
|
1787
|
+
minifyIdentifiers: true,
|
1788
|
+
minifySyntax: true,
|
1789
|
+
minifyWhitespace: true,
|
1790
|
+
mangleQuoted: true,
|
1791
|
+
exclude: []
|
1792
|
+
}
|
1793
|
+
}
|
1794
|
+
});
|
1795
|
+
```
|
1507
1796
|
|
1508
1797
|
# CLI Usage
|
1509
1798
|
|
@@ -1523,9 +1812,9 @@ If you are using a package manager like [pnpm](https://pnpm.js.org/en/cli/instal
|
|
1523
1812
|
|
1524
1813
|
### Commands
|
1525
1814
|
|
1526
|
-
The Syncify CLI
|
1815
|
+
The Syncify CLI supports the following commands.
|
1527
1816
|
|
1528
|
-
```
|
1817
|
+
```bash
|
1529
1818
|
Default:
|
1530
1819
|
syncify Starts interactive CLI command prompt
|
1531
1820
|
|
@@ -1536,21 +1825,26 @@ Commands:
|
|
1536
1825
|
syncify Starts interactive CLI command prompt
|
1537
1826
|
syncify <store> --flags Store name or comma separated list of stores and flags
|
1538
1827
|
|
1539
|
-
|
1540
|
-
-t, --theme <targets>
|
1828
|
+
Flags:
|
1829
|
+
-t, --theme <targets> A comma separated list of theme targets
|
1541
1830
|
-b, --build Triggers a build, use with upload to run build before uploading
|
1542
1831
|
-w, --watch Starts watching for changes of files building when they occur
|
1543
1832
|
-u, --upload Uploads theme to online store, use with -t to target theme
|
1544
1833
|
-d, --download Downloads themes/s from specified stores
|
1545
|
-
-
|
1546
|
-
-
|
1547
|
-
-
|
1548
|
-
-s, --
|
1549
|
-
-o, --output
|
1834
|
+
-c, --config <path> An optional config path to the syncify.config.js file.
|
1835
|
+
-h, --hot HOT Reloading (available in watch mode only)
|
1836
|
+
-p, --package Package theme and export to a .zip file
|
1837
|
+
-s, --spawn, <name> Target a specific spawn (use with -w or -b flags to specify mode)
|
1838
|
+
-o, --output <path> A path value (used in download and build mode only)
|
1550
1839
|
-h, --help, Prints command list and some help information
|
1551
|
-
-
|
1552
|
-
-
|
1553
|
-
|
1840
|
+
-f, --filter <filter> Query online store data API, eg: themes, metafields assets
|
1841
|
+
-v, --version <action> Version control resource mode (see version arguments)
|
1842
|
+
|
1843
|
+
Resource Modes:
|
1844
|
+
--metafields Metafields resource mode
|
1845
|
+
--locales Locales resource mode
|
1846
|
+
--settings Settings resource mode
|
1847
|
+
--redirects Redirects resource mode
|
1554
1848
|
|
1555
1849
|
Version Arguments:
|
1556
1850
|
patch Increments the package.json version patch, eg: 1.0.0 > 1.0.1
|
@@ -1558,25 +1852,31 @@ Version Arguments:
|
|
1558
1852
|
major Increments the package.json version major, eg: 1.0.0 > 2.0.0
|
1559
1853
|
|
1560
1854
|
Operation Flags:
|
1855
|
+
--clean Removes all output files, use with --build to clean before bundling
|
1561
1856
|
--status Checks development environment and connections are valid.
|
1562
1857
|
--pull Pull data from online store
|
1563
1858
|
--merge Merge online data with local references
|
1859
|
+
--force Forces a sync, replacing remote source with local one
|
1860
|
+
--silent Silence the logger, omit only errors
|
1564
1861
|
|
1565
1862
|
Generator Flags:
|
1566
1863
|
--vsc Generates JSON schema spec for vscode users
|
1864
|
+
--strap <name> Generates a Syncify theme strap, eg: --strap dawn
|
1567
1865
|
|
1568
1866
|
Environment Flags:
|
1569
1867
|
--dev, --development Run in development mode (default)
|
1570
1868
|
--prod, --production Run in production mode
|
1571
1869
|
```
|
1572
1870
|
|
1573
|
-
|
1871
|
+
> Please keep in mind that not all commands are active as the project is still in beta.
|
1574
1872
|
|
1575
|
-
|
1873
|
+
## Examples
|
1874
|
+
|
1875
|
+
CLI usage aims to be as simple as possible. A typical project will be targeting a single Shopify theme but you can target multiple themes and stores in a seamless manner. When targeting multiple stores or themes the CLI employs a flag based naming approach.
|
1576
1876
|
|
1577
1877
|
**Generate theme targets**
|
1578
1878
|
|
1579
|
-
```
|
1879
|
+
```bash
|
1580
1880
|
$ syncify store-name -q themes
|
1581
1881
|
```
|
1582
1882
|
|
@@ -1588,8 +1888,8 @@ Prompt interface will be initialized
|
|
1588
1888
|
|
1589
1889
|
**Generate local metafields**
|
1590
1890
|
|
1591
|
-
```
|
1592
|
-
$ syncify store-name
|
1891
|
+
```bash
|
1892
|
+
$ syncify store-name --metafields --pull
|
1593
1893
|
```
|
1594
1894
|
|
1595
1895
|
Prompt interface will be initialized
|
@@ -1600,8 +1900,8 @@ Prompt interface will be initialized
|
|
1600
1900
|
|
1601
1901
|
**Upload theme to online store**
|
1602
1902
|
|
1603
|
-
```
|
1604
|
-
$ syncify store-name -t theme-1,theme-2
|
1903
|
+
```bash
|
1904
|
+
$ syncify store-name -t theme-1,theme-2 --clean -b -u --prod
|
1605
1905
|
```
|
1606
1906
|
|
1607
1907
|
Exchange interface will be initialized
|
@@ -1614,7 +1914,7 @@ Exchange interface will be initialized
|
|
1614
1914
|
|
1615
1915
|
**Watching 1 store and 1 theme**
|
1616
1916
|
|
1617
|
-
```
|
1917
|
+
```bash
|
1618
1918
|
$ syncify shop -w -t dev
|
1619
1919
|
```
|
1620
1920
|
|
@@ -1637,14 +1937,12 @@ The `package.json` configuration for the command would look like this:
|
|
1637
1937
|
```jsonc
|
1638
1938
|
{
|
1639
1939
|
"syncify": {
|
1640
|
-
"stores":
|
1641
|
-
|
1642
|
-
|
1643
|
-
"
|
1644
|
-
"dev": 123456789 // The theme id and target name
|
1645
|
-
}
|
1940
|
+
"stores": {
|
1941
|
+
"domain": "cool-shop", // The store name
|
1942
|
+
"themes": {
|
1943
|
+
"dev": 123456789 // The theme id and target name
|
1646
1944
|
}
|
1647
|
-
|
1945
|
+
}
|
1648
1946
|
}
|
1649
1947
|
}
|
1650
1948
|
```
|
@@ -1653,8 +1951,8 @@ The `package.json` configuration for the command would look like this:
|
|
1653
1951
|
|
1654
1952
|
**Watching 1 store and 2 themes**
|
1655
1953
|
|
1656
|
-
```
|
1657
|
-
$ syncify shop -
|
1954
|
+
```bash
|
1955
|
+
$ syncify shop -t dev,prod -w
|
1658
1956
|
```
|
1659
1957
|
|
1660
1958
|
<details>
|
@@ -1676,15 +1974,13 @@ The `package.json` configuration for the command would look like this:
|
|
1676
1974
|
```jsonc
|
1677
1975
|
{
|
1678
1976
|
"syncify": {
|
1679
|
-
"stores":
|
1680
|
-
|
1681
|
-
|
1682
|
-
"
|
1683
|
-
|
1684
|
-
"prod": 123456789 // The theme id and target name
|
1685
|
-
}
|
1977
|
+
"stores": {
|
1978
|
+
"domain": "my-shop", // The store name
|
1979
|
+
"themes": {
|
1980
|
+
"dev": 123456789, // The theme id and target name
|
1981
|
+
"prod": 123456789 // The theme id and target name
|
1686
1982
|
}
|
1687
|
-
|
1983
|
+
}
|
1688
1984
|
}
|
1689
1985
|
}
|
1690
1986
|
```
|
@@ -1693,8 +1989,8 @@ The `package.json` configuration for the command would look like this:
|
|
1693
1989
|
|
1694
1990
|
**Watching 2 stores and multiple themes**
|
1695
1991
|
|
1696
|
-
```
|
1697
|
-
$ syncify shop1,shop2
|
1992
|
+
```bash
|
1993
|
+
$ syncify shop1,shop2 --shop1=test --shop2=dev,stage,prod -w
|
1698
1994
|
```
|
1699
1995
|
|
1700
1996
|
<details>
|
@@ -1754,8 +2050,8 @@ Syncify can be initialized within scripts. This approach is a little more featur
|
|
1754
2050
|
|
1755
2051
|
Syncify exports a function that has several methods which you can use to trigger specific modes. The default export can also target multiple hooks in accordance with what was passed from the command line.
|
1756
2052
|
|
1757
|
-
```
|
1758
|
-
import { syncify } from '@
|
2053
|
+
```ts
|
2054
|
+
import { syncify } from '@syncify/cli';
|
1759
2055
|
|
1760
2056
|
// Build hook
|
1761
2057
|
syncify.build(options: {}, async function(content?: Buffer): Promise<Buffer|string|void|false>);
|
@@ -1781,10 +2077,10 @@ syncify(options: {})({
|
|
1781
2077
|
|
1782
2078
|
### Utilities
|
1783
2079
|
|
1784
|
-
Utilities will return some basic information about the Syncify instance. These are extremely helpful when when you are executing spawned processes and need to control what feature to load. For example, if you are spawning a webpack process for compiling JavaScript assets and need to inform upon watch mode you'd use `util.resource('watch')` which returns a boolean value when running in watch mode.
|
2080
|
+
Utilities will return some basic information about the Syncify instance. These are extremely helpful when when you are executing [spawned](#spawn) processes and need to control what feature to load. For example, if you are spawning a webpack process for compiling JavaScript assets and need to inform upon watch mode you'd use `util.resource('watch')` utility which returns a boolean value when running in watch mode.
|
1785
2081
|
|
1786
2082
|
```typescript
|
1787
|
-
import { util, env } from '
|
2083
|
+
import { util, env } from '@syncify/cli'
|
1788
2084
|
|
1789
2085
|
// Environment Conditions
|
1790
2086
|
env.prod: boolean;
|
@@ -1805,20 +2101,6 @@ util.spawned(): string[]
|
|
1805
2101
|
|
1806
2102
|
```
|
1807
2103
|
|
1808
|
-
### Backwards Compatibility
|
1809
|
-
|
1810
|
-
Syncify supports backward compatibility for [shopify-sync](https://github.com/panoply/shopify-sync). This allows you to use it as you would have in earlier versions with build tools like [Gulp](https://gulpjs.com).
|
1811
|
-
|
1812
|
-
> Please note this support for this will eventually be deprecated.
|
1813
|
-
|
1814
|
-
```typescript
|
1815
|
-
import { shopifysync as sync } from '@liquify/syncify';
|
1816
|
-
|
1817
|
-
// Backward compatible, ie: shopify-sync
|
1818
|
-
sync(mode: string, options: {}, function() {})
|
1819
|
-
|
1820
|
-
```
|
1821
|
-
|
1822
2104
|
# Contributing
|
1823
2105
|
|
1824
2106
|
This project uses [pnpm](https://pnpm.js.org/en/cli/install). Fork the project, run `pnpm i` and you're good to go. If you're using Yarn like the rest of the plebs or npm then you will still need to install pnpm.
|