{"id":33914609,"url":"https://github.com/nebulab/shopify_theme_builder","last_synced_at":"2026-01-16T07:50:32.245Z","repository":{"id":326350242,"uuid":"1092471557","full_name":"nebulab/shopify_theme_builder","owner":"nebulab","description":"An opinionated builder for Shopify themes using nested folders, Tailwind CSS, and Stimulus","archived":false,"fork":false,"pushed_at":"2025-12-15T10:08:28.000Z","size":65,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-18T10:09:45.264Z","etag":null,"topics":["builder","shopify","shopify-theme","shopify-theme-development","stimulusjs","tailwindcss"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/nebulab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-08T17:29:52.000Z","updated_at":"2025-12-15T10:08:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nebulab/shopify_theme_builder","commit_stats":null,"previous_names":["nebulab/shopify_theme_builder"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/nebulab/shopify_theme_builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nebulab%2Fshopify_theme_builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nebulab%2Fshopify_theme_builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nebulab%2Fshopify_theme_builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nebulab%2Fshopify_theme_builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nebulab","download_url":"https://codeload.github.com/nebulab/shopify_theme_builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nebulab%2Fshopify_theme_builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["builder","shopify","shopify-theme","shopify-theme-development","stimulusjs","tailwindcss"],"created_at":"2025-12-12T06:35:09.808Z","updated_at":"2026-01-13T21:58:07.714Z","avatar_url":"https://github.com/nebulab.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ShopifyThemeBuilder\n\n![Gem Version](https://img.shields.io/gem/v/shopify_theme_builder?logo=rubygems)\n![GitHub branch check runs](https://img.shields.io/github/check-runs/nebulab/shopify_theme_builder/main?logo=github)\n![Codecov](https://img.shields.io/codecov/c/github/nebulab/shopify_theme_builder)\n![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/rubygems/shopify_theme_builder)\n![Gem Total Downloads](https://img.shields.io/gem/dt/shopify_theme_builder)\n![GitHub License](https://img.shields.io/github/license/nebulab/shopify_theme_builder)\n\nShopifyThemeBuilder is a Ruby gem that facilitates the development of Shopify themes by enabling the use of a components folder where you can organize your files and separate liquid, JSON, CSS, JavaScript, comment and doc into a dedicated file. It watches for changes in your component folder and automatically compiles all files into Shopify-compatible Liquid templates.\n\n## What problem does it solve?\n\nShopify themes have a specific structure where different types of files are stored in designated folders. For example:\n- Sections: Contains Liquid files that define the structure and layout of different sections of the theme.\n- Blocks: Contains reusable Liquid files that can be included in sections.\n- Snippets: Contains reusable Liquid files that can be included in other files.\n\nAll these files are stored in the `sections`, `blocks`, and `snippets` folders respectively and cannot be organized in subfolders.\n\nAdditionally, all files can include JSON, comments, docs, CSS and JavaScript code, which must be included in the main Liquid file, resulting in large and hard-to-maintain files.\n\n## How does it work?\n\nShopifyThemeBuilder allows you to create a `components` folder (default is `_components`) where you can organize your theme files in a more modular way. Each component can have its own comments, docs, Liquid, JSON, CSS, and JavaScript files. When you run the watcher, it monitors changes in the components folder and automatically compiles the files into the appropriate Shopify theme structure. Example:\n\n```\n_components/\n  button/\n    comment.txt\n    doc.txt\n    block.liquid\n    schema.json\n    style.css\n    index.js\n    controllers.js\nassets/\n  tailwind-output.css\n  tailwind.css\n  controllers.js\nblocks/\n  button.liquid\n```\n\nAll files inside the `button` folder will be compiled into a single `button.liquid` file in the `blocks` folder, combining the comment, doc, Liquid, JSON, CSS, and JavaScript code.\n\n## Tailwind CSS Support\n\nShopifyThemeBuilder also supports Tailwind CSS integration. You can specify an input CSS file that includes Tailwind directives and an output CSS file where the compiled styles will be saved. The watcher will automatically run the Tailwind build process whenever changes are detected in the components folder.\n\n## Stimulus JS Support\n\nShopifyThemeBuilder supports Stimulus JS integration. You can specify an output JavaScript file where the compiled Stimulus controllers will be saved. The watcher will automatically compile the Stimulus controllers whenever changes are detected in the components folder.\n\n### How to create Stimulus controllers\n\nTo create Stimulus controllers, create a `controller.js` file inside your component folder. For example:\n\n```\n_components/\n  my_component/\n    controller.js\n```\n\nThe content of the `controller.js` file should follow the Stimulus controller structure. For example:\n\n```javascript\nclass HelloController extends Controller {\n  connect() {\n    console.log(\"My component controller connected\")\n  }\n}\n\nStimulus.register(\"hello\", HelloController)\n```\n\nWhen the watcher runs, it will compile all `controller.js` files from your components into a single JavaScript file that can be included in your Shopify theme.\n\n## Installation\n\nInstall the gem and add to the application's Gemfile by executing:\n\n```bash\nbundle add shopify_theme_builder --group \"development\"\n```\n\nRun the gem's install command:\n\n```bash\nbundle exec theme-builder install\n```\n\nThis will inject Tailwind CSS and Stimulus JS into your Shopify theme layout, and add an entry in the `Procfile.dev` to run the watcher if present.\n\n## Usage\n\nTo watch for changes in the default components folder and build the theme, run:\n\n```bash\nbundle exec theme-builder watch\n```\n\nYou can customize multiple options when running the watcher:\n- `--folders`: Specify one or more folders to watch (default is `_components`).\n- `--tailwind-input-file`: Specify the Tailwind CSS input file (default is `./assets/tailwind.css`).\n- `--tailwind-output-file`: Specify the Tailwind CSS output file (default is `./assets/tailwind-output.css`).\n- `--skip-tailwind`: Skip the Tailwind CSS build process (default is `false`).\n- `--stimulus-output-file`: Specify the Stimulus JS output file (default is `./assets/controllers.js`).\n\nIf you need help with all available options, or how to set them, run:\n\n```bash\nbundle exec theme-builder help watch\n```\n\n### Component generator\n\nThis gem also provides a command to generate a new component with all the necessary files. To create a new component, run:\n\n```bash\nbundle exec theme-builder generate\n```\n\nYou can customize the component type, name and folder by providing additional options:\n- `--type`: Specify the component type (`section`, `block`, or `snippet`).\n- `--name`: Specify the component name.\n- `--folder`: Specify the components folder (default is `_components`).\n\n## Tested With\n\n- [Skeleton Theme](https://github.com/Shopify/skeleton-theme)\n- [Horizon Theme](https://github.com/Shopify/horizon)\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, run `bin/release VERSION`, which will update the version file, create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Next Steps\n\n- [x] Run the tailwind build process automatically.\n- [x] Add Stimulus JS support.\n- [x] Create a command to build an example component with all the files.\n- [ ] Investigate if it's possible to use import maps instead of a single file for Stimulus controllers.\n- [ ] Decompile existing Shopify files into components structure (Is it really needed?).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/nebulab/shopify_theme_builder.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnebulab%2Fshopify_theme_builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnebulab%2Fshopify_theme_builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnebulab%2Fshopify_theme_builder/lists"}