🥭 About The Project

Mango is made to work in tandem with Shopify Theme Kit, Webpack and a little bit of NodeJS magic.

The goal of mango, was to provide developers with a quick and easy setup to start using modern day technologies when doing Shopify development and to solve the baseline issues Theme Kit was having.

Mango makes sure all needed Theme Kit & web pack commands are ran in conjunction with one another, while working out of one terminal.

Mango aims to provide a set ideology, with a direct and concise Project Scaffolding to allow for rapid and modern development on Shopify.

🥭 Built With

Mango is purely open source and built with NodeJS.

🥭 Getting Started

🥭 Installation

npm install @shopackify/mango -g

🥭 Usage

🥭 Initializing a Project

mango init will set up the base project, copy all of the configuration files.

🥭 Files Mango rely on

Mango actively looks for:

1. webpack.config.js
2. webpack.production.config.js
3. config.yml

These files should be in your project root at all times.

🥭 Configuration Files

config.yml

• Stores all of your Shopify environment data, mango will read and write from this when needing to make API calls.

development:
  password: example_password
  theme_id: "1234567890123"
  store: example.myshopify.com
  directory: shop/dist
  ignores:
  - themekit_ignores
  
staging:
  password: example_password
  theme_id: "1234567890123"
  store: example.myshopify.com
  directory: shop/dist
  ignores:
  - themekit_ignores
  
production:
  password: example_password
  theme_id: "1234567890123"
  store: example.myshopify.com
  directory: shop/dist
  ignores:
  - themekit_ignores

webpack.config.js and webpack.production.config.js

• Mango uses both of these files as core files. The production config is only ever used on build, and the standard config is used while watching. To learn more about webpack configuration files see: https://webpack.js.org/

🥭 Opinionated

Mango is an opinionated build tool and expects you to follow the outlined structure to properly work, however you can edit the webpack.production.config.js & webpack.config.js files to suit your needs.

🥭 What to expect

Using the recommended config mango init or will setup the project directory with all of the recommended configurations out of the box.

🥭 Directory Structure

  |-- shop
      |-- dist
          |-- assets
          |-- config
          |-- layout
          |-- locales
          |-- sections
          |-- snippets
          |-- templates
              |-- customers
      |-- src
          |-- config
          |-- dev
              |-- fonts
              |-- images
              |-- js
                  |-- modules
                  		|-- *.js
              |-- static
                  |-- static-files
                  		|-- *.*
              |-- styles
                  |-- base
                  		|-- *.css
                  |-- components
                  		|-- *.css
                  |-- mixins
                  		|-- *.css
                  |-- sections
                  		|-- *.css
                  |-- templates
                  		|-- *.css
                  |-- typography
                  		|-- *.css
                  |-- variables
                  		|-- *.css
          |-- layout
          |-- locales
          |-- sections
          |-- snippets
          |-- templates
              |-- customers

🥭 Mango Commands

Mango Audit

• mango audit - Audits the /shop/src directory for unusued settings from settings_schema.json, unusued snippets from /shop/src/snippets and unusued locales from your *.default.json locale file.

• Will output a mango-audit.md file with the results from the audit.

Mango Build

• mango build - Builds the distrobution /shop/dist folder ready for deployment from the /shop/src directory.

Optional flags:

1. -env --environment - The environment from your config.yml that you would like to use to update your settings_schema.json with.

Mango Config

• mango config - Will setup the config.yml file required for Shopify themes to work.

Required flags:

1. -t --themeid - The theme id you'd like to work with
2. -p --password - The password of the admin app you use to communicate with Shopify.
3. -s --store - The .myshopify url of the store you want to work on.

Optional flags:

1. -i --ignores - The ignores file you want to use, defaults to .shopifyignores
2. -e --env - The environment you want to use, defaults to development
3. -d --dir - The directory for themekit to watch, defaults to ./shop/dist

Mango Convert

• mango convert - Will take the theme structure you have in shop/dist and convert it to work with mango, sometimes there's manual steps required.

Mango Deploy

• mango deploy - Will deploy the /shop/dist folder to the current theme.

Optional flags:

1. -d --dir - Which directory to deploy (default: /shop/dist)
2. -l --allow-live - Allow deployment to the live theme
3. -e --env - Which environment to use (default: development)
4. -n --new - Specify whether or not to generate a new theme to deploy to
5. -v --verbose - Specify if you want Verbose output
6. -i --ignores - The ignores file you want to use

Mango Download

mango download - Will download the currently defined theme in your config.yml file.

Mango Style-Link

mango style-link - A manual command to dynamically link any of your styles you have defined to be linked using <!-- mango-link: mango.style.css -->, this will find the file in the shop/dist/assets directory and inline it accordingly.

NOTES: Mango style-link happens at build time and during development, you will hardly need to run this command manually if at all.

Mango Init

mango init - Will initialize the project directory for mango ready builds.

Mango Install

mango install - Runs on npm i @shopackify/mango -g to install the bin for theme kit, can manually run to update the theme kit bin.

Mango Locales

mango locales - Compiles your locales folder with the configured localization defined in shop/src/dev/locales.config.json example:

{
  "locales": ["en.default", "ja"],
  "translations": {
    "404": {
      "general": {
        "title": "Page not found"
      }
    }
  }
}

Mango Update-Data

mango updata-data - Update config/settings_data.json with the published theme settings_data.json

Optional flags:

1. -env --environment - Specify whether or not to update the settings_data.json file with a config from the live or specified theme id.

Mango Watch

mango watch - Will start watching for file changes.

Optional flags:

1. -env --environment - Specify environment from the config.yml fil, wrap in quotes to pass multiple: -e "development1 development2"

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Zacarie Carr - LinkedIn - [email protected]

Project Link: Mango NPM Link: Mango

Acknowledgements

• Shopify
• Themekit
• Webpack
• Webpack-Cli
• Fast-Glob
• Fs-Extra
• Ora
• Chokidar
• WS
• Babel
• Sass
• Postcss
• Best README Template