Developing

Developing the toolkit

Start by running yarn install from the root directory. You must have Yarn v3 installed. If you don’t refer to its installation (opens in a new tab)).

Then, run yarn dev:toolkit for compiling the packages used by templates. Keep this running on a separate terminal at all times. Then, you'll either run yarn dev:template:base or yarn dev:template:shopify, according to the template you're editing at the time. To set-up the templates, do the following:

  1. Have the projectId, dataset and a write token for a Sanity project in hands. We recommend one project for the base template and another for the store.
  2. Populate these values in a new .env file in packages/remix-cli/dev-templates/TEMPLATE_NAME following the convention of .env.sample in the same folder
  3. Run yarn dev:template:TEMPLATE_NAME from the root folder to develop the toolkit packages
    • Reach out to Henrique if you need projects to test with
  4. The Remix front-end will be available at localhost:3000, with the Sanity studio at localhost:3000/manage
  5. Edit the files in the root templates folder, not the one in packages/remix-cli/templates nor dev-templates
🛑

Careful when editing the template

Don't add project-specific components to it. The templates folder is shipped with the @tinloof/remix-cli package, so if you want to test out a feature for a client, create a new project with the CLI and work from that newly created folder.

Understanding the templates workflow

In the root templates directory, you'll find 2 templates, base and shopify. We keep the templates at the root folder to make it easier for new collaborators to locate them. For distributing to npm and have them accessible by the CLI code for creating new projects, both are copied into packages/remix-cli.

Locally, the dev:toolkit script introduced above will use the templates folder to create/update test projects in inside packages/remix-cli/dev-templates. That's where you actually run your code from when you run yarn dev:template:NAME. This extra folder & set-up is needed as the shopify template isn't complete and requires some reused files from base.

As there's no package installed in the root templates folder, which would break Typescript definitions and relative imports, we point the TS definitions to the folders in remix-cli/dev-templates. This works most of the time, but you can't follow the definition of a given symbol as that'll take you to the development folder, which will be overwritten with new changes in the de-factor template source. Be sure you're always working from the /templates directory.

If you have suggestions on how to improve this workflow, they're highly requested, it'd be a pleasure to receive them ✨

Testing the CLI flows

  1. While npm run dev:toolkit is running from the root directory, open a new terminal and run npm run dev:cli to start the locally developed CLI
  2. New changes made in the CLI code will be compiled with the dev command, so you can immediately run the CLI command again to see them into effect.

When testing the creation of the template, run the CLI and go through the new project creation in its entirety. Once the project is created, open its folder in another terminal and:

  1. populate its .env
  2. run npm i
  3. npm run dev
  4. Open localhost:3000 and test critical flows
Common pitfallsIn-depth architecture guide