{"id":21826314,"url":"https://github.com/unshopable/liquidx","last_synced_at":"2025-04-14T05:24:42.080Z","repository":{"id":170368190,"uuid":"644767176","full_name":"unshopable/liquidx","owner":"unshopable","description":"XML-like syntax extension to Shopify's Liquid template language","archived":false,"fork":false,"pushed_at":"2023-11-29T19:36:12.000Z","size":132,"stargazers_count":14,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T19:14:48.997Z","etag":null,"topics":["liquid","shopify","shopify-theme","xml"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/unshopable.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-05-24T08:04:42.000Z","updated_at":"2024-03-20T11:00:34.000Z","dependencies_parsed_at":"2023-11-29T20:43:30.098Z","dependency_job_id":null,"html_url":"https://github.com/unshopable/liquidx","commit_stats":null,"previous_names":["unshopable/liquidx"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unshopable%2Fliquidx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unshopable%2Fliquidx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unshopable%2Fliquidx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unshopable%2Fliquidx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unshopable","download_url":"https://codeload.github.com/unshopable/liquidx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248825595,"owners_count":21167516,"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":["liquid","shopify","shopify-theme","xml"],"created_at":"2024-11-27T18:03:37.703Z","updated_at":"2025-04-14T05:24:42.074Z","avatar_url":"https://github.com/unshopable.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LiquidX\n\nLiquidX is a XML-like syntax extension to Shopify's Liquid template language. It's not intended to run on Shopify's servers, thus needs to be used by preprocessors (transpilers) to transform it into standard Liquid.\n\n```liquid\n\u003cGrid columns=\"{{ 2 }}\"\u003e\n  \u003cGridItem\u003e\n    \u003cMedia placeholder=\"product-1\" /\u003e\n  \u003c/GridItem\u003e\n\n  \u003cGridItem\u003e\n    \u003cVerticalStack class=\"h-full\" gap=\"{{ 8 }}\" align=\"center\"\u003e\n      \u003cVerticalStack gap=\"{{ 2 }}\"\u003e\n        \u003cText as=\"h2\" variation=\"heading3\"\u003eProduct 1\u003c/Text\u003e\n\n        \u003cText\u003e\n          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt\n          ut \u003cstrong\u003elabore et dolore\u003c/strong\u003e magna aliqua. Ut enim ad minim veniam, quis nostrud\n          exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n        \u003c/Text\u003e\n      \u003c/VerticalStack\u003e\n\n      \u003cButton plain icon_right=\"arrow-right\"\u003eLearn more\u003c/Button\u003e\n    \u003c/VerticalStack\u003e\n  \u003c/GridItem\u003e\n\u003c/Grid\u003e\n```\n\n![liquidx-preview](https://github.com/unshopable/liquidx/assets/64148345/1a4fcdc3-bae2-4f64-85c7-5056a4795db9)\n\n## Table of Contents\n\n- [Motivation](#motivation)\n- [Getting started](#getting-started)\n- [Components](#components)\n  - [Props](#props)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Motivation\n\nThe purpose of LiquidX is to improve the developer experience and speed up the development process tremendously – we're talking 10x here. It achieves this goal by making it almost trivial to implement design systems and component libraries.\n\nOut of the box, Liquid does not support nested structures for components (aka snippets) which makes it hard – or even impossible in some cases – to create really reusable components. LiquidX introduces a concise and familiar syntax for defining tree structures with attributes while adding almost no syntactic footprint.\n\n## Getting started\n\n\u003e **Note**\n\u003e If you're not using any build tools yet, the fastest way to implement LiquidX is [Melter](https://github.com/unshopable/melter) with the [LiquidX Melter Plugin](https://github.com/unshopable/melter-plugin-liquidx).\n\nThis package exports a `render` function which expects a string. If this string contains LiquidX syntax than it's rendered to Shopify-compatible code.\n\nTo illustrate how easy it is to implement LiquidX yourself in your Shopify theme projects, we'll do a quick implementation with [Melter](https://github.com/unshopable/melter).\n\nAssuming that you already installed Melter, create a new file:\n\n```diff\n  melter-liquidx\n  ├── node_modules\n  ├── src\n  │    └── ...\n  ├── melter.config.js\n+ ├── liquidx-plugin.js\n  ├── package-lock.json\n  └── package.json\n```\n\n**liquidx-plugin.js**\n\n```js\nconst { render } = require('@unshopable/liquidx');\nconst { Plugin } = require('@unshopable/melter');\n\nclass LiquidXPlugin extends Plugin {\n  apply(compiler): void {\n    compiler.hooks.emitter.tap('LiquidXPlugin', (emitter) =\u003e {\n      emitter.hooks.beforeAssetAction.tap('LiquidXPlugin', (asset) =\u003e {\n        if (asset.action !== 'remove') {\n          asset.content = Buffer.from(render(asset.content.toString()));\n        }\n      });\n    });\n  }\n}\n\nmodule.exports = LiquidXPlugin;\n```\n\nNow add this to your melter config:\n\n```diff\n+ const LiquidXPlugin = require('./liquidx-plugin.js');\n\n  /** @type {import(\"@unshopable/melter\").MelterConfig} */\n  const melterConfig = {\n+   plugins: [\n+     new LiquidXPlugin(),\n+   ],\n  };\n\n  module.exports = melterConfig;\n```\n\n## Components\n\nNow that LiquidX is ready to be transpiled, let's talk about how to create components. Let's take a look at an example.\n\nFirst, create some new files:\n\n```diff\n  melter-liquidx\n  ├── node_modules\n  ├── src\n+ │   ├── snippets\n+ │   │   └── button.liquid\n+ │   └── sections\n+ │       └── section.liquid\n  ├── melter.config.js\n  ├── liquidx-plugin.js\n  ├── package-lock.json\n  └── package.json\n```\n\n\u003e **Note**\n\u003e We recommend creating a dedicated directory for components to have a clear distinction between \"snippets\" and \"components\". This can easily be configured with the `paths` option in Melter.\n\n**components/button.liquid**\n\n```liquid\n\u003cbutton\u003e{{ children }}\u003c/button\u003e\n```\n\n**sections/section.liquid**\n\n```liquid\n\u003cButton\u003eClick me!\u003c/Button\u003e\n```\n\nIn this example `{{ children }}` will render \"Click me!\".\n\nIt's important to understand, that components are basically just native Shopify snippets that give access to an optional `children` property.\n\nYou could also rewrite the example above:\n\n```diff\n- \u003cbutton\u003e{{ children }}\u003c/button\u003e\n+ \u003cButton children=\"Click me!\" /\u003e\n```\n\nWith this in mind you can start building reusable UI components. For instance, you can update the `button` component so it can either be a `\u003cbutton\u003e` or `\u003ca\u003e`:\n\n**components/button.liquid**\n\n```diff\n+ {%- liquid\n+   # Determine tag name and optional attributes of the underlying element (button or anchor).\n+\n+   assign tag_name = 'button'\n+   assign inner_attrs = null\n+\n+   if url\n+     assign tag_name = 'a'\n+     assign href_attr = 'href=\"' | append: url | append: '\"' | sort\n+     assign inner_attrs = inner_attrs | concat: href_attr\n+   endif\n+ -%}\n+\n+ \u003c{{ tag_name }}{{ inner_attrs | join: ' ' }}\u003e{{ children }}\u003c/button\u003e\n- \u003cbutton\u003e{{ children }}\u003c/button\u003e\n```\n\n**sections/section.liquid**\n\n```liquid\n\u003cButton\u003eI'm a Button!\u003c/Button\u003e\n\u003cButton url=\"/cart\"\u003eI'm a Link!\u003c/Button\u003e\n```\n\nThis renders:\n\n```liquid\n\u003cbutton\u003eI'm a Button!\u003c/button\u003e\n\u003ca href=\"/cart\"\u003eI'm a Link!\u003c/a\u003e\n```\n\n### Props\n\nProps can be of any type Liquid supports:\n\n```liquid\n\u003cMyComponent\n  string1=\"string\"\n  string2=\"1337\"\n  string3=\"{{ '1337' }}\"\n  number=\"{{ 1 }}\"\n  float=\"{{ 1.5 }}\"\n  boolean1=\"{{ true }}\"\n  boolean2\n  variable=\"{{ cart }}\"\n  ...\n/\u003e\n```\n\nFor a smooth developer experience make sure to document all available props in your component:\n\n```diff\n+ {% comment %}\n+   Renders a button component.\n+\n+   @param {string} [url] - A destination to link to, rendered in the href attribute of a link.\n+   @param {any} children\n+\n+   @example\n+\n+   \u003cButton\u003eAdd to Cart\u003c/Button\u003e\n+ {% endcomment %}\n+\n  {%- liquid\n    # Determine tag name and optional attributes of the underlying element (button or anchor).\n\n    assign tag_name = 'button'\n    assign inner_attrs = null\n\n    if url\n      assign tag_name = 'a'\n      assign href_attr = 'href=\"' | append: url | append: '\"' | sort\n      assign inner_attrs = inner_attrs | concat: href_attr\n    endif\n  -%}\n\n  \u003c{{ tag_name }}{{ inner_attrs | join: ' ' }}\u003e{{ children }}\u003c/button\u003e\n```\n\n\u003e **Note**\n\u003e This \"LiquidDoc\" is also what will be used to power intellisense/autocompletion in VSCode in a later release.\n\n## Contributing\n\nTODO\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funshopable%2Fliquidx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funshopable%2Fliquidx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funshopable%2Fliquidx/lists"}