# shopify-symlinks

> This package allows for the development process for a Shopify to be component based. Files can be organized by their function and their relationships with other components.

Latest version **2.0.3** (published 2024-08-23) · ISC license · 3 weekly downloads

## Install

```sh
npm install shopify-symlinks
pnpm add shopify-symlinks
yarn add shopify-symlinks
bun add shopify-symlinks
```

Provides the command `shopify-symlinks`.

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.3 |
| Published | 2024-08-23 |
| First published | 2024-08-22 |
| Weekly downloads | 3 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 25.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Daryl Blancaflor |
| Maintainers | djblanc360 |
| Keywords | shopify, symlink, symbolic link |

## Links

- npm: https://www.npmjs.com/package/shopify-symlinks
- npm.io page: https://npm.io/package/shopify-symlinks

## Dependencies (1)

- [commander](https://npm.io/package/commander.md) ^12.1.0

## Alternatives

- [monaco-yaml](https://npm.io/package/monaco-yaml.md) — 420.1K weekly downloads
- [@crewx/workflow](https://npm.io/package/@crewx/workflow.md) — 3.1K weekly downloads
- [yaml-cat](https://npm.io/package/yaml-cat.md) — 38 weekly downloads
- [nunjucks-in-yaml](https://npm.io/package/nunjucks-in-yaml.md) — 9 weekly downloads
- [@fozikio/reflex](https://npm.io/package/@fozikio/reflex.md) — 0 weekly downloads

## Recent versions

- 2.0.3 (latest) — 2024-08-23
- 2.0.2 — 2024-08-23
- 2.0.0 — 2024-08-22
- 1.0.0 — 2024-08-22

## README

# Shopify Symlinks for Component Based Directory Structure

This package serves as both a CLI tool and a build utility specifically for Shopify and so far only tested with Vite. This build process reflects my ideal development process for a Shopify theme. This project is my attempt to organize the architecture for large-scale Shopify websites.

This is my first npm package so it's definitely strict, unrefined and unoptimized. I welcome any feedback to improve this service for developers who share my thought process in organizing various components by their function and their relationships with other components.

 ## Features
* Uses Node fsPromise symbolic links to facilitate the creation of new components in this component based architecture. 

* Liquid files created in `components/` directory will be auto linked to their respective shopify theme location.

* Scripts in `components/` directory will be auto included in `main.js` and added to `assets/` directory.

* Created a `utilities/` directory where `symlinks.js` will bundle each file in folder to a single `utils.js` file in `assets/` directory

### Example Liquid File:
`header.liquid` file in `components/header/sections/` while running `npx shopify-symlinks` should create a `header.liquid` file in `sections/`. The origin is set to the newly created `sections/header.liquid`. Then a symlink is created to reference any changes from the `components/header/sections/header.liquid` file.

### Example JavaScript File:
`index.js` file in `components/header/index.js` while running `npx shopify-symlinks`
should create a `header.js` file in `assets/`. The origin is set to the newly created `assets/header.js`. Then a symlink is created to reference any changes from the `components/header/index.js` file.

`nav.js` file in `components/header/nav.js` while running `npx shopify-symlinks`
should create a `header_nav.js` file in `assets/`. The origin is set to the newly created `assets/header_nav.js`. Then a symlink is created to  reference any changes from the `components/header/nav.js` file.

The content of `polling.js` file in `utilities/` directory is bundled into `utils.js` file in `assets/` directory.

## Usage

### Installation
```
npm install -D shopify-symlinks 
```

optional `package.json`
```
  "scripts": {
    "dev": "shopify-symlinks"
  },
```


### Run Options
```
npx shopify-symlinks
```

run with custom entrypath
```
npx shopify-symlinks -- --entry custom/entry/path.js
```

watch with dynamic list of directories and default `main.js` entrypoint
```
npx shopify-symlinks -- --watch server,integrations
```

### Example Development to Production Process

1.
run `npx shopify-symlinks`
- Create file `components/sections/product.liquid` is moved to `sections/product.liquid`, the reference to the origin `components/sections/product.liquid` is saved. 
- `sections/product.liquid` becomes the new origin and the reference to the `components/sections/product.liquid` origin is retrieved.
- A symbolic link `sections/product.liquid` from `components/sections/product.liquid` is created.
- when pushing to github ,`sections/product.liquid` has the code and `components/sections/product.liquid` has the reference to `sections/product.liquid`.

2.
run `npm run pull`
- Section schema is created in `components/sections/product.liquid`.
- The contents of a particular section using that schema is updated in the Shopify Admin.
- In another terminal, run the command to retrieve the updated cusom settings.
- When viewing on shopify store, will just see a string local file reference to `components/sections/product.liquid`.

3.
on `npm run build` or `shopify theme share`
- Run `reverse-symlinks.js`.
- So now `sections/product.liquid` has the code and `components/sections/product.liquid` has the reference to `sections/product.liquid`.
- When viewing on shopify store, should see actual content of `product.liquid`.

 
 ## Example Implementation for Vite
 `vite.config.js`:
 ```
import { defineConfig } from 'vite';
import shopify from 'vite-plugin-shopify';

export default defineConfig({
  plugins: [
    shopify()
  ],
  build: {
    emptyOutDir: false,
    rollupOptions: {
      input: {
        main: './frontend/entrypoints/main.js',
        styles: './frontend/entrypoints/main.css',
      },
      output: {
        entryFileNames: '[name]-[hash].js',
        assetFileNames: '[name]-[hash][extname]',
        dir: 'assets',
      }
    }
  },
  resolve: {
    preserveSymlinks: true, // ensure vite follows symlink
  },
  server: { // ensure handling of symlinks and live reload
    watch: {
      usePolling: true, // watch for changes in symlinked files 
      interval: 200, // adjust since chokidar is default 100
      include: ['**/*.liquid'], // explicit to reinforce on change
    }
  }
});
 ```

 
## Added Dependencies
- **commander**: For command line.
- **chokidar**: To simplify file watching cross platform.
- **vite-plugin-shopify**: for Vite integration in Shopify themes.


## Future Updates

* optimize symbolic link initialization

* create symbolic link for `.css` files in the `components/` directory

* auto include peripheral directories specified to be watched in 

* auto update `.shopifyignore` with dynamic list of watched peripheral directories

* enforce or recommend pulling of only `templates/` and `config/settings_data.json` to prevent overwriting

* handle use with webpack and themekit

## Authors

* [@Daryl Blancaflor](djblanc360@gmail.com)

## Version History

* 2.0.0
  * fixed check of `
  * On `npm run dev` creates `components/` and `utilities/` directories if none exist
  * On `npm run dev` adds watched directories including `components/` and `utilities/` directories to a `.shopifyignore` file, create a `.shopifyignore` if none exist

---
_Source: https://npm.io/package/shopify-symlinks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._