odestry/adastra

Adastra is a powerful, flexible framework for building unique and custom Shopify themes with next-gen frontend tools.

Adastra ✨ is a powerful and flexible framework for building custom and unique —
Shopify Themes with next-gen frontend tooling.

Install

The recommended way to scaffold an Adastra ✨ theme project is by running the command below:

npm create adastra@latest

Using Yarn/PNPM

yarn create adastra@latest
# pnpm create adastra@latest

Adastra came from the Latin word Ad-astra which stands for To the Stars ✨

Key Features ✨

• Flexible Can seamlessly be integrated with existing workflows and Shopify themes.
• Outstanding DX Lightning Fast HMR for static files and has custom CLI built on top of the Shopify CLI.
• Fast, by default Supports modules/scripts code splitting and lazyloading static files.
• UI-agnostic Supports React, Preact, Solid, Vue, Solid, Lit and more. (more examples coming soon)
• Customizable Sensible built-in default configs for use in existing themes and highly extensible.

Requirements

Please make sure you have these two already set up in your local environment.

• Node.js version 14 or higher (LTS recommended)
• Shopify Theme CLI version 3.0.0 or higher

Packages

Package	Changelog	Version
adastra-plugin	CHANGELOG
adastra-cli	CHANGELOG
adastra-cli-kit	CHANGELOG
create-adastra	CHANGELOG
adastra-branding	CHANGELOG
adastra-prettier-config	CHANGELOG

Examples & Templates

Adastra ✨ comes with so many examples to showcase, how it can be used with all of these frontend tools and ui frameworks, to build next generation online storefronts.

Theme/Example	Command
Basics Template (Tailwind & Prettier)	npm create adastra@latest -- --template basics
Minimal Template	npm create adastra@latest -- --template minimal
Necessary Template	npm create adastra@latest -- --template necessary
Example with React	npm create adastra@latest -- --template blanklob/adastra/examples/with-react
Example with Vue	npm create adastra@latest -- --template blanklob/adastra/examples/with-vue
Example with Preact	npm create adastra@latest -- --template blanklob/adastra/examples/with-preact
Example with Solid	npm create adastra@latest -- --template blanklob/adastra/examples/with-solid
Example with Typescript	npm create adastra@latest -- --template blanklob/adastra/examples/with-typescript
Example with Lit	npm create adastra@latest -- --template blanklob/adastra/examples/with-lit
Example with Alpine	npm create adastra@latest -- --template blanklob/adastra/examples/with-alpine
Example with Tailwind	npm create adastra@latest -- --template blanklob/adastra/examples/with-tailwind
Example with GSAP	npm create adastra@latest -- --template blanklob/adastra/examples/with-gsap
Example with Sass	npm create adastra@latest -- --template blanklob/adastra/examples/with-sass
Example with Less	npm create adastra@latest -- --template blanklob/adastra/examples/with-less
Example with Vanilla Extract	npm create adastra@latest -- --template blanklob/adastra/examples/with-vanilla-extract
Example with React Three Fiber	npm create adastra@latest -- --template blanklob/adastra/examples/with-r3f
Example with React Hydrogen	npm create adastra@latest -- --template blanklob/adastra/examples/with-hydrogen

More examples coming soon.

Documentation

Currently web documentation is under construction 🚧 you can check docs on every package.

• Adastra Plugin Docs (here)
• Adastra CLI Docs (here)
• Adastra Create Theme CLI (here)

Roadmap

This project is maintained, and I'm currently building it in public. You can follow the progress on Twitter @blanklob. You can find the roadmap here as well.

Support & Contributing

New contributors Welcome! Check out our Contributors Guide for help getting started.

Having trouble? Get help in the official Discord and meet other Shopify developers who build using Adastra ✨

Special Thanks

• Shopify CLI for inspiring Adastra ✨ CLI.
• Shopify Vite Plugin for inspiring the Vite plugin.
• Astro for inspiring the Create Adastra CLI.
• Hydrogen for inspiring development principles and architecture.

adastra's Issues

add customURL option to adastraTagSnippetDev to let it work with ngrok #42

Hi! 👋

Firstly, thanks for your work on this project! 🙂

Today I used patch-package to patch [email protected] for the project I'm working on.

Here is the diff that solved my problem:

diff --git a/node_modules/adastra-plugin/dist/index.cjs b/node_modules/adastra-plugin/dist/index.cjs
index 3c1655e..03d5258 100644
--- a/node_modules/adastra-plugin/dist/index.cjs
+++ b/node_modules/adastra-plugin/dist/index.cjs
@@ -41,7 +41,8 @@ var resolveOptions = ({
   sourceDir = "src",
   entrypointsDir = "entrypoints",
   additionalEntrypoints = [],
-  snippetName = "adastra"
+  snippetName = "adastra",
+  ngrokUrl = "localhost:5173"
 }) => {
   const resolvedEntrypointsDir = import_path.default.join(sourceDir, entrypointsDir);
   return {
@@ -49,7 +50,8 @@ var resolveOptions = ({
     sourceDir,
     entrypointsDir: resolvedEntrypointsDir,
     additionalEntrypoints,
-    snippetName
+    snippetName,
+    ngrokUrl
   };
 };
 
@@ -191,12 +193,12 @@ var adastraEntryTag = (entryPaths, tag, isFirstEntry = false) => `{% ${!isFirstE
 var preloadScriptTag = (fileName) => `<link rel="modulepreload" href="{{ '${fileName}' | asset_url | split: '?' | first }}" as="script" crossorigin="anonymous">`;
 var scriptTag = (fileName) => `<script src="{{ '${fileName}' | asset_url | split: '?' | first }}" type="module" crossorigin="anonymous"></script>`;
 var stylesheetTag = (fileName) => `{{ '${fileName}' | asset_url | split: '?' | first | stylesheet_tag: preload: preload }}`;
-var adastraTagSnippetDev = (assetHost, entrypointsDir) => `{% liquid
+var adastraTagSnippetDev = (assetHost, entrypointsDir, ngrokUrl) => `{% liquid
   assign path_prefix = path | slice: 0
   if path_prefix == '/'
-    assign file_url_prefix = '${assetHost}'
+    assign file_url_prefix = '${(ngrokUrl) ? ngrokUrl : assetHost}'
   else
-    assign file_url_prefix = '${assetHost}/${entrypointsDir}/'
+    assign file_url_prefix = '${(ngrokUrl) ? ngrokUrl : assetHost}/${entrypointsDir}/'
   endif
 
   assign file_url = path | prepend: file_url_prefix
@@ -259,10 +261,10 @@ function resolveDevServerUrl(address, config) {
 }
 function isIpv6(address) {
   return address.family === "IPv6" || // In node >=18.0 <18.4 this was an integer value. This was changed in a minor version.
-  // See: https://github.com/laravel/vite-plugin/issues/103
-  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-  // @ts-expect-error-next-line
-  address.family === 6;
+    // See: https://github.com/laravel/vite-plugin/issues/103
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error-next-line
+    address.family === 6;
 }
 
 // src/plugins/vite-plugin-adastra-liquid.ts
@@ -292,8 +294,10 @@ var vite_plugin_adastra_liquid_default = (options) => {
             config2.resolve.alias,
             options.entrypointsDir,
             adastraSnippetName
-          ) + adastraTagSnippetDev(devServerUrl, options.entrypointsDir);
+          ) + adastraTagSnippetDev(devServerUrl, options.entrypointsDir, options.ngrokUrl);
           import_fs.default.writeFileSync(adastraSnippetPath, adastraTagSnippetContent);
+
+          console.log("options", options)
         }
       });
       return () => middlewares.use((req, res, next) => {
diff --git a/node_modules/adastra-plugin/dist/index.js b/node_modules/adastra-plugin/dist/index.js
index 1b6476b..8ae4edc 100644
--- a/node_modules/adastra-plugin/dist/index.js
+++ b/node_modules/adastra-plugin/dist/index.js
@@ -208,6 +208,7 @@ var adastraTagSnippetDev = (assetHost, entrypointsDir) => `{% liquid
 
 // src/utilities/dev-server.ts
 function resolveDevServerUrl(address, config) {
+  console.log('resolveDevServerUrl', config);
   const configHmr = config.server.hmr;
   const configHmrProtocol = typeof configHmr === "object" ? configHmr.protocol : null;
   const configHmrHost = typeof configHmr === "object" ? configHmr.host : null;
@@ -223,10 +224,10 @@ function resolveDevServerUrl(address, config) {
 }
 function isIpv6(address) {
   return address.family === "IPv6" || // In node >=18.0 <18.4 this was an integer value. This was changed in a minor version.
-  // See: https://github.com/laravel/vite-plugin/issues/103
-  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-  // @ts-expect-error-next-line
-  address.family === 6;
+    // See: https://github.com/laravel/vite-plugin/issues/103
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error-next-line
+    address.family === 6;
 }
 
 // src/plugins/vite-plugin-adastra-liquid.ts

This issue body was partially generated by patch-package.

[FEAT] Create a more stable entrypoints pattern in the liquid Adastra plugin

WHY are these changes introduced?

These changes are intruced to fix one issue with entrypoint files. Currently when you cant to make an entryoint file you have to do it in 2 steps:

1. Create the entrypoint file inside the root direcotory (default src)
2. Add entrypoint render liquid tag

This means that any file inside the root will be considered as an entrypoint file, which will generate useless files and they will be copied to the assets folder without them being used.

This problem needs to be adressed as soon as possible, because with larger project the current root file decision deosn't scale, and will produce issues where files are being copied to the assets folder, like type definition files.

WHAT is this pull request doing?

How to test your changes?

Post-release steps

Update checklist

• I've added a CHANGELOG entry for this PR
• I've considered possible cross-platform impacts (Mac, Linux, Windows).
• I've left the version number as is (we'll handle incrementing this when releasing).
• I've included any post-release steps in the section above (if needed).

[BUG][CLI] Yarn dev bugs out

My machine uses rbenv and indeed I have ruby 3.1.2 and 3.2.0 installed, but for some reason, Shopify CLI bugs out on me not having 3.1.0 which is kinda dumb on that tooling.

yarn dev --store=booger-wooger.myshopify.com
Adastra Initiating launch sequence for booger-wooger store

To run this command, log in to Shopify Partners.
👉 Press any key to open the login page on your browser
✔ Logged in.
── external error ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Error coming from bundle install

Command failed with exit code 1: bundle install
rbenv: version `3.1.0' is not installed (set by /Users/gimpygumpy/Documents/Shops/2023/adastra/node_modules/@shopify/cli-kit/assets/cli-ruby/.ruby-version)

[FEAT][CLI] Add a create adastra command utils

[BUG] Error on first dev run

┏━━ Error ━━━━━━━━━━━━━━━━━━
┃ The option --overwrite-json is not supported.
┗━━━━━━━━━━━━━━━━━━━━━━━

My config:
node --version
v16.14.0

yarn --version
1.22.19

shopify version
3.43.0

[REFACTOR] Updates `templates` folder and add the correct examples with a proper root README

WHY are these changes introduced?

These changes are introduced to update the two templates that originally come with Adastra, and also to add a README to the root templates folder, explaining how templates work, and hot scaffold an Adastra project from existing templates.

WHAT is this pull request doing?

• Add standard theme linting to check for errors.
• Add README to the root /templates folder.
• Add both templates to the mono repo.
• Update the templates and remove non-used code like Codespaces integration.
• Update packages.json for required changes.
• Add theme check CI to workflows

How to test your changes?

• Manual test by running Adastra CLI commands in the root of the theme folder and Checking for console errors, when in development mode.
• Run theme check to see if there are any errors with the two templates.
• Run the two development servers separately without using the CLI.
• Check if Liquid and src file changes are enabled through HMR and HOT RELOAD.

Post-release steps

Update the two templates repositories with the new changes. For basic template and minimal template

Update checklist

• I've added a CHANGELOG entry for this PR
• I've considered possible cross-platform impacts (Mac, Linux, Windows).
• I've left the version number as is (we'll handle incrementing this when releasing).
• I've included any post-release steps in the section above (if needed).

[DOCS] Create and docs website

[BUG] Fix and refactor Create Adastra CLI cause it deosn't work on windows machines.

[TEST][PLUGIN] Fix tests with the Adastra plugin

[BUG][CLI] Theme Editor glitchy

So there is a link provided as:

 Customize this theme in the Theme Editor, and use 'theme pull' to get the changes:

And that indeed loads up the theme in the store, and one can preview/customize. The thing is, this comes with a glitchy experience where the Theme Editor relentlessly issues POST requests to Shopify, simply by hovering the mouse around theme editor, not doing anything... not editing anything anyway. I have not seen this poor behaviour before, and it likely has nothing to do with Adastra, but man, it sucks. Poor experience anyway... Shopify needs to do better me thinks.

add customURL option to adastraTagSnippetDev to let it work with ngrok

Hi! 👋

Firstly, thanks for your work on this project! 🙂

Today I used patch-package to patch [email protected] for the project I'm working on.

Here is the diff that solved my problem:

diff --git a/node_modules/adastra-plugin/dist/index.cjs b/node_modules/adastra-plugin/dist/index.cjs
index 3c1655e..4dbbab9 100644
--- a/node_modules/adastra-plugin/dist/index.cjs
+++ b/node_modules/adastra-plugin/dist/index.cjs
@@ -63,6 +63,7 @@ var vite_plugin_adastra_config_default = (options) => {
   return {
     name: "adastra-plugin-config",
     config(config) {
+      console.log(config);
       const host = config.server?.host ?? "localhost";
       const port = config.server?.port ?? 5173;
       const https = config.server?.https;
@@ -191,12 +192,12 @@ var adastraEntryTag = (entryPaths, tag, isFirstEntry = false) => `{% ${!isFirstE
 var preloadScriptTag = (fileName) => `<link rel="modulepreload" href="{{ '${fileName}' | asset_url | split: '?' | first }}" as="script" crossorigin="anonymous">`;
 var scriptTag = (fileName) => `<script src="{{ '${fileName}' | asset_url | split: '?' | first }}" type="module" crossorigin="anonymous"></script>`;
 var stylesheetTag = (fileName) => `{{ '${fileName}' | asset_url | split: '?' | first | stylesheet_tag: preload: preload }}`;
-var adastraTagSnippetDev = (assetHost, entrypointsDir) => `{% liquid
+var adastraTagSnippetDev = (assetHost, entrypointsDir, ngrokUrl) => `{% liquid
   assign path_prefix = path | slice: 0
   if path_prefix == '/'
-    assign file_url_prefix = '${assetHost}'
+    assign file_url_prefix = '${(ngrokUrl) ? ngrokUrl : assetHost}'
   else
-    assign file_url_prefix = '${assetHost}/${entrypointsDir}/'
+    assign file_url_prefix = '${(ngrokUrl) ? ngrokUrl : assetHost}/${entrypointsDir}/'
   endif
 
   assign file_url = path | prepend: file_url_prefix
@@ -244,6 +245,7 @@ var adastraTagSnippetDev = (assetHost, entrypointsDir) => `{% liquid
 
 // src/utilities/dev-server.ts
 function resolveDevServerUrl(address, config) {
+  console.log('resolveDevServerUrl', config);
   const configHmr = config.server.hmr;
   const configHmrProtocol = typeof configHmr === "object" ? configHmr.protocol : null;
   const configHmrHost = typeof configHmr === "object" ? configHmr.host : null;
@@ -259,10 +261,10 @@ function resolveDevServerUrl(address, config) {
 }
 function isIpv6(address) {
   return address.family === "IPv6" || // In node >=18.0 <18.4 this was an integer value. This was changed in a minor version.
-  // See: https://github.com/laravel/vite-plugin/issues/103
-  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-  // @ts-expect-error-next-line
-  address.family === 6;
+    // See: https://github.com/laravel/vite-plugin/issues/103
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error-next-line
+    address.family === 6;
 }
 
 // src/plugins/vite-plugin-adastra-liquid.ts
@@ -292,7 +294,7 @@ var vite_plugin_adastra_liquid_default = (options) => {
             config2.resolve.alias,
             options.entrypointsDir,
             adastraSnippetName
-          ) + adastraTagSnippetDev(devServerUrl, options.entrypointsDir);
+          ) + adastraTagSnippetDev(devServerUrl, options.entrypointsDir, options.ngrokUrl);
           import_fs.default.writeFileSync(adastraSnippetPath, adastraTagSnippetContent);
         }
       });
diff --git a/node_modules/adastra-plugin/dist/index.js b/node_modules/adastra-plugin/dist/index.js
index 1b6476b..8ae4edc 100644
--- a/node_modules/adastra-plugin/dist/index.js
+++ b/node_modules/adastra-plugin/dist/index.js
@@ -208,6 +208,7 @@ var adastraTagSnippetDev = (assetHost, entrypointsDir) => `{% liquid
 
 // src/utilities/dev-server.ts
 function resolveDevServerUrl(address, config) {
+  console.log('resolveDevServerUrl', config);
   const configHmr = config.server.hmr;
   const configHmrProtocol = typeof configHmr === "object" ? configHmr.protocol : null;
   const configHmrHost = typeof configHmr === "object" ? configHmr.host : null;
@@ -223,10 +224,10 @@ function resolveDevServerUrl(address, config) {
 }
 function isIpv6(address) {
   return address.family === "IPv6" || // In node >=18.0 <18.4 this was an integer value. This was changed in a minor version.
-  // See: https://github.com/laravel/vite-plugin/issues/103
-  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-  // @ts-expect-error-next-line
-  address.family === 6;
+    // See: https://github.com/laravel/vite-plugin/issues/103
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error-next-line
+    address.family === 6;
 }
 
 // src/plugins/vite-plugin-adastra-liquid.ts

This issue body was partially generated by patch-package.

[Feature]: need examples of Hydrogen and Preact.

What area(s) will this request affect?

Examples

What type of change do you want to see?

New feature

Overview

I'm concerned about id conflicts if there are multiple Sections on the same page, since I do it for id elements when I create them in React. Therefore, I think it would be better to be able to prepare it in WebComponents. Thus, Preact and lit are good examples, but we would also like to use Hydrogen's functionality. So if this is feasible, I would like to see an example.

Motivation

I was working on Theme App Extension with Preact + Tailwind + WebComponents and thought how happy I would be if I could develop the theme itself with the same experience. That's when I found this repository and asked a question.

[FEAT][EXAMPLES] Finish and standardize the base example and make it as minimalistic as possible (recommended)

[BUG][CLI] Scafold command to launch dev store takes time to launch

I am stuck at adastra initializing launch sequence. after running npm run dev i am already login to my store.

[DOCS] Add README explaining how to use Adastra and how to get started

Get started template

1 - Added an images banner for Adastra
2 - Add workflow badges
3 - Add a getting started guide
4 - Added a link to example demo in the link page
5 - Simplifier and remove usless files
6 - Explain that this is a beta access repo

[REFACTOR][PLUGIN] Remove unused modules architecture

WHY are these changes introduced?

Currently, the plugin imported from the Barrel Shopify Vite repository has a secondary entry points directory to support the second modules Vite plugin, since we don't use modules we should instead remove the code used by this Plugin inside Adastra plugin to avoid any issues in the long run.

No context.

WHAT is this pull request doing?

This PR removes unused code and tests used by the modules Vite plugin.

How to test your changes?

Post-release steps

Update checklist

• I've added a CHANGELOG entry for this PR
• I've considered possible cross-platform impacts (Mac, Linux, Windows).
• I've left the version number as is (we'll handle incrementing this when releasing).
• I've included any post-release steps in the section above (if needed).

[Bug]: Adastra build command removes custom fonts

Please confirm that you have:

• Searched existing issues to see if your issue is a duplicate. (If you’ve found a duplicate issue, feel free to add additional information in a comment on it.)
• Reproduced the issue in the latest CLI version.

In which of these areas are you experiencing a problem?

CLI

Expected behavior

Hi Adastra team,

I'm using Adastra for the first time on my client project. I'm using custom fonts in the assets folder, but when I run npm run build, the custom fonts are removed.

How can I run the build command without deleting my custom fonts?

Thanks,
Ulziibat

Actual behavior

When I run npm run build, the custom fonts are removed.

Stack trace

No response

Reproduction steps

1. copy the custom fonts to the assets folder
2. npm run build
3. custom fonts are removed

Operating System

Mac OS Monterey

Adastra CLI version (check your project's package.json if you're not sure)

latest

Shell

zsh

Node version (run node -v if you're not sure)

v20.0.0

What language and version are you using in your application?

ruby 3.0.4p208 (2022-04-12 revision 3fa771dded) [arm64-darwin21], git version 2.40.1