{"id":24437111,"url":"https://github.com/notixbit/shopify-collection-dsl","last_synced_at":"2025-09-05T18:39:31.605Z","repository":{"id":40568833,"uuid":"236535027","full_name":"notixbit/shopify-collection-dsl","owner":"notixbit","description":"Create Custom- and Smart Collections for Shopify programmatically.","archived":false,"fork":false,"pushed_at":"2022-12-12T01:19:41.000Z","size":40,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T11:05:18.059Z","etag":null,"topics":["collection","customcollection","dsl","e-commerce","shopify","shopify-collection","smartcollection"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/notixbit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-27T16:23:27.000Z","updated_at":"2023-11-02T17:58:31.000Z","dependencies_parsed_at":"2023-01-27T09:40:13.470Z","dependency_job_id":null,"html_url":"https://github.com/notixbit/shopify-collection-dsl","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notixbit%2Fshopify-collection-dsl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notixbit%2Fshopify-collection-dsl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notixbit%2Fshopify-collection-dsl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notixbit%2Fshopify-collection-dsl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/notixbit","download_url":"https://codeload.github.com/notixbit/shopify-collection-dsl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248599294,"owners_count":21131257,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collection","customcollection","dsl","e-commerce","shopify","shopify-collection","smartcollection"],"created_at":"2025-01-20T18:15:22.317Z","updated_at":"2025-04-12T16:42:25.138Z","avatar_url":"https://github.com/notixbit.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# shopify-collection-dsl\n\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Build Status](https://travis-ci.com/notixbit/shopify-collection-dsl.svg?branch=master)](https://travis-ci.com/notixbit/shopify-collection-dsl) [![npm version](https://badge.fury.io/js/%40notixbit%2Fshopify-collection-dsl.svg)](https://badge.fury.io/js/%40notixbit%2Fshopify-collection-dsl)\n\nCreate Custom- and Smart Collections for Shopify programmatically.\n\nThis module is using [Shopify-api-node](https://github.com/MONEI/Shopify-api-node) for communicating with the Shopify API.\n\nFeatures:\n  * [CustomCollection](https://help.shopify.com/en/api/reference/products/customcollection#create-2020-01) \u0026 [SmartCollection](https://help.shopify.com/en/api/reference/products/smartcollection#create-2020-01)\n  * ES8 (async/await)\n  * ES6 (Promises)\n  * Debugging (dry-run)\n  * Tests\n\n---\n\n# Table of contents\n* [Use Case](#use-case)\n* [CustomCollection](#customcollection)\n  * [API Reference](#api-reference)\n  * [Method Reference](#method-reference)\n    * [Create a CustomCollection instance](#create-a-customcollection-instance)\n    * [Set title](#set-title)\n    * [Set sort-order](#set-sort-order)\n    * [Set scope](#set-scope)\n    * [Set body (description)](#set-body-description)\n    * [Set image](#set-image)\n    * [Create the collection](#create-the-collection)\n* [SmartCollection](#smartcollection)\n  * [API Reference](#api-reference-1)\n  * [Method Reference](#method-reference-1)\n    * [Create a SmartCollection instance](#create-a-smartcollection-instance)\n    * [Add rule](#add-rule)\n    * [Set disjunctive](#set-disjunctive)\n* [Setup / Install](#setup--install)\n* [Unit-Tests](#unit-tests)\n  * [Make](#make)\n  * [NPM](#npm)\n* [Contributing](#contributing)\n* [License](#license)\n\n---\n\n# Use Case\n\nHere at Notixbit, one of our customers wanted us to create 40+ Smart Collections including \nmultiple rules for those collections. Using the Shopify-API was a no-brainer for us, and so we\nstarted writing a parser that would allow us to programmatically create those collections.\nThe parser reads data from a local/remote database while provisioning the collections that are needed for the customers shop.\n\nThis module (shopify-collection-dsl) is a wrapper around Shopify-api-node, and we decided\nto separate it from the parser and release it as an Open Source project.\n\n---\n\n# CustomCollection\n\n## API Reference\n\n```javascript\nCustomCollection(\n    [String=title]\n) -\u003e Object {\n    /* Constants */\n    this: Object=this\n    opts: Object=this.opts\n\n    /* Methods */\n    title: [String=title] | this\n    sort: [String=order] | this\n    scope: [String=scope] | this\n    body: [String=html] | this\n    image: [Object=image] | this\n    async create: [Shopify=shopify, Boolean=dryrun, Object=opts] | Promise\n}\n\n```\n\n---\n\n## Method reference:\n\n### Create a CustomCollection instance\n\n**Available options:**\n\n| Argument | Description | Required |\n| ------ | ----------- | ------ | \n| title | The collection title | Yes | \n\n```javascript\nconst collection = new CustomCollection('my-title')\n```\n---\n\n### Set title\n\nYou can change the collection title by calling the ``.title`` method, too.\u003cbr\u003e\n\n**Available arguments:**\n\n| Argument | Description | Default |\n| ------ | ----------- | ----- |\n| title | The collection title | None |\n\n```javascript\ncollection.title('my-title')\n```\n\n---\n\n### Set sort-order\n\n**Available arguments:**\n\n| Argument | Description | Default |\n| ------ | -----------  | ----- |\n| order | The sort-order | manual |\n\nReference:\u003cbr\u003e\n\n```\nalpha-asc: Alphabetically, in ascending order (A - Z).\nalpha-desc: Alphabetically, in descending order (Z - A).\nbest-selling: By best-selling products.\ncreated: By date created, in ascending order (oldest - newest).\ncreated-desc: By date created, in descending order (newest - oldest).\nmanual: Order created by the shop owner.\nprice-asc: By price, in ascending order (lowest - highest).\nprice-desc: By price, in descending order (highest - lowest).\n```\n[See Documentation\t\n](https://help.shopify.com/en/api/reference/products/customcollection)\u003cbr\u003e\n\n```javascript\ncollection.sort('alpha-asc')\n```\n\n---\n\n### Set scope\n\n**Available arguments:**\n\n| Argument | Description | Default |\n| ------ | -----------  | ----- |\n| scope | The scope | global |\n\nReference:\u003cbr\u003e\n\n```\nweb: The custom collection is published to the Online Store channel but not published to the Point of Sale channel.\n\nglobal: The custom collection is published to both the Online Store channel and the Point of Sale channel.\n```\n[See Documentation\t\n](https://help.shopify.com/en/api/reference/products/customcollection)\u003cbr\u003e\n\n```javascript\ncollection.scope('web')\n```\n\n---\n\n### Set body (description)\n\n**Available arguments:**\n\n| Argument | Description | Default |\n| ------ | -----------  | ----- |\n| html | The description | None |\n\n[See Documentation\t\n](https://help.shopify.com/en/api/reference/products/customcollection)\u003cbr\u003e\n\n```javascript\ncollection.body('Great \u003cb\u003eshoes\u003c/b\u003e for men!')\n```\n\n---\n\n### Set image\n\n**Available arguments:**\n\n| Argument | Description | Default |\n| ------ | -----------  | ----- |\n| image | The image | none |\n\nReference:\u003cbr\u003e\n\n```\nattachment: An image attached to a custom collection returned as Base64-encoded binary data.\nsrc: The source URL that specifies the location of the image.\nalt: Alternative text that describes the collection image.\ncreated_at: The time and date (ISO 8601 format) when the image was added to the collection.\nwidth: The width of the image in pixels.\nheight: The height of the image in pixels.\n```\n[See Documentation\t\n](https://help.shopify.com/en/api/reference/products/customcollection)\u003cbr\u003e\n\n```javascript\ncollection.image({\n  'src': 'http://example.com/shoes.png',\n  'alt': 'Shoes picture'\n})\n```\n\n---\n\n### Create the collection\n\n**Available arguments:**\n\n| Argument | Description | Default |\n| ------ | -----------  | ----- |\n| shopify | Shopify module instance | none |\n| dryrun | Whether to debug the request | false |\n| opts | Override internal ``this.opts`` | this.opts |\n\n\n```javascript\nawait collection.create(shopify)\n\n// or\n\ncollection.create(shopify)\n  .then()\n  .catch()\n```\n\nTo debug (dry-run) the payload for the request,\u003cbr\u003e\nsimply pass ``true`` to the ``.create`` method. \n\n```javascript\nconst payload = await collection.create(shopify, true)\nconsole.log(payload)\n```\n\n---\n\n# SmartCollection\n\n## API Reference\n\n```javascript\nSmartCollection extends CustomCollection(\n    [String=title]\n) -\u003e Object {\n    /* Constants */\n    this: Object=this\n    opts: Object=this.opts\n\n    /* Methods */\n    title: [String=title] | this\n    sort: [String=order] | this\n    scope: [String=scope] | this\n    body: [String=html] | this\n    image: [String=image] | this\n    rule: [String=column, String=relation, String=condition] | this\n    disjunctive: [] | this\n    async create: [Shopify=shopify, Boolean=dryrun, Object=opts] | Promise\n}\n\n```\n\n---\n\n## Method reference:\n\nA SmartCollection instance inherits all CustomCollection methods, including two additional methods.\n\n### Create a SmartCollection instance\n\n**Available options:**\n\n| Argument | Description | Required |\n| ------ | ----------- | ------ | \n| title | The collection title | Yes | \n\n```javascript\nconst collection = new SmartCollection('my-title')\n```\n---\n\n### Add rule\n\nYou can set multiple rules for your Smart Collection.\u003cbr\u003e\n\n**Available arguments:**\n\n| Argument | Description | Default |\n| ------ | ----------- | ----- |\n| rule | The rule | None |\n\n[See Documentation\t\n](https://help.shopify.com/en/api/reference/products/smartcollection)\u003cbr\u003e\n\n```javascript\ncollection.rule('title', 'contains', 'shoes')\n```\n\nChain them like so:\n\n```javascript\ncollection\n  .rule('title', 'contains', 'shoes')\n  .rule('vendor', 'equals', 'Nike')\n```\n\n\n\n\n---\n\n### Set disjunctive\n\nIf this method is called, the internal ``opts.disjunctive`` is set to ``true``,\u003cbr\u003e\notherwise it is set to ``false``.\n\n```\ntrue: Products only need to match one or more of the rules to be included in the smart collection.\nfalse: Products must match all of the rules to be included in the smart collection.\n```\n[See Documentation\t\n](https://help.shopify.com/en/api/reference/products/smartcollection)\u003cbr\u003e\n\n```javascript\ncollection.disjunctive()\n```\n\n---\n\n## Setup / Install\n\nUse `npm install @notixbit/shopify-collection-dsl` \n\n```javascript\nconst { \n  Shopify, \n  CustomCollection, \n  SmartCollection \n} = require('@notixbit/shopify-collection-dsl')\n\nconst shopify = new Shopify({\n  'shopName': 'your-shop',\n  'apiKey': 'your-key',\n  'password': 'your-pw'\n})\n\n// Now you can create Custom Collections...\nconst collection = new CustomCollection('my-collection')\n\nawait collection\n  .body('Great products for young people')\n  .sort('best-selling')\n  .create(shopify)\n\n// ... and/or Smart Collections\n\nconst collection = new SmartCollection('my-collection')\n\nawait collection\n  .body('Great products for young people')\n  .sort('best-selling')\n  .rule('title', 'contains', 'shoes')\n  .rule('vendor', 'equals', 'Nike')\n  .disjunctive()\n  .create(shopify)\n```\n\n---\n\n## Unit-Tests\n\nThe testing-framework used in this module is [Mocha](https://github.com/mochajs/mocha) with the BDD / TDD assertion library [Chai](https://github.com/chaijs/chai).\n\n* test/test.default.js `Performs 4 tests` | [Source](../master/test/test.default.js)\n\nOutput using [Mocha](https://github.com/mochajs/mocha) `list` reporter:   \n\n\u003cimg src=\"https://i.imgur.com/3vrrRHc.png\" /\u003e\n\nDefault reporter: `list`\n\n### Make\n\n```make test```\n\n### NPM\n\n```npm test```\n\n---\n\n## Contributing\n\nYou're very welcome and free to contribute. Thank you.\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotixbit%2Fshopify-collection-dsl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnotixbit%2Fshopify-collection-dsl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotixbit%2Fshopify-collection-dsl/lists"}