ggt - the Gadget CLI 

Gadget's CLI, named ggt, is the command-line interface for the Gadget platform.

ggt provides additional functionality for working with your Gadget applications using your existing tools on your machine. ggt isn't required for building end-to-end Gadget apps but supports syncing files locally (and more soon) for your preferred coding experience.

For in-depth documentation about ggt and its commands, visit the GitHub repository.

Cloning files 

ggt allows you to clone your app's files into a local directory and sync any changes between your local directory and the Gadget editor (in real time!).

With your app's files on your local computer, you can use your favorite code editor, like VSCode or Sublime, to work on your Gadget apps. You can set up your own lint rules, write and run unit tests like you would any other Node project, use your local command line to add npm modules, not to mention push your code to a repo such as GitHub. This allows you to implement version control and enables multiple developers to contribute code to the same Gadget project.

ggt sync clones your Gadget app's files to and from your local filesystem, but your Gadget app still runs in the cloud. Changes made locally are immediately reflected in Gadget, so you can build and test your app using the rest of Gadget's tools as you would normally. The Editor, API Playground, and your application's API will all live-update to reflect your changes and are suitable for testing your cloned files.

Getting Started 

The quickest way to clone your files is to run the following in your terminal:

Terminal
Shell
npx ggt@latest sync ~/gadget/example-app --app=example-app

This will copy example-app's files into your ~/gadget/example-app directory.

Once started, ggt sync will continue to sync files between your app and your local directory. The syncing works in both directions: any file changes in your local directory will be synced back to Gadget, and changes in Gadget will be synced to your local directory.

ggt sync will continue to run in the background until you stop it manually.

Next steps 

Running npx ggt@latest sync ~/gadget/example-app --app=example-app is a great way to get started, but it can be a bit tedious to type over and over again. Thankfully, you can do a few things to make it easier.

Step 1: Install ggt globally

Installing ggt globally is as simple as running the following in your terminal:

Terminal
yarn global add ggt
npm install --global ggt

You can verify that ggt was properly installed by running ggt --help. Once you have verified that the install was successful, you can use ggt anywhere in your terminal -- no need for npx!

You can use yarn or npm to download ggt. But yarn is required to add additional packages to a Gadget project.

Step 2: Skip the --app flag

ggt sync remembers which app was used to sync a local directory. Therefore, when you sync to the same directory again, you can skip the --app flag.

Terminal
Shell
# After the first sync, the following are identical
ggt sync ~/gadget/example-app
ggt sync ~/gadget/example-app --app=example-app

Step 3: Skip the directory

By default, ggt sync will sync to the directory that you are currently in.

Terminal
Shell
# When you're already inside your local directory, the following are identical
ggt sync
ggt sync .
ggt sync ~/gadget/example-app

There we go! 🎉

We turned npx ggt@latest sync ~/gadget/example-app --app=example-app into a simple ggt sync.

Now, whenever you're ready to start developing your app locally, it's as simple as:

Terminal
Shell
cd ~/gadget/example-app
ggt sync

Resolving conflicts 

If you make changes locally or pull changes down from version control and then start running ggt sync, you might find that you have conflicts. The same file may have been edited locally and in the Gadget app since the last sync was run.

Thankfully, ggt will detect conflicts for you. It will also give you a couple of different options for resolving conflicts:

  • Cancel (Ctrl+C): You can choose to cancel the sync operation
  • Keep my conflicting changes: Keep your local conflicting changes and overwrite Gadget's.
  • Keep Gadget's conflicting changes: Keep Gadget's conflicting changes and overwrite your local ones.

Note that these options will keep the conficting changes for all file conflicts! In the example below, selecting either option will overwrite changes to both routes/GET.js and routes/POST-order.js files.

Terminal
Shell
$ ggt sync
You have conflicting changes with Gadget
You Gadget
routes/GET.js ± updated ± updated
routes/POST-order.js ± updated - deleted
? How would you like to resolve these conflicts?
> Cancel (Ctrl+C)
Keep my conflicting changes
Keep Gadget's conflicting changes

If there are changes you want to keep from both your local filesystem and Gadget environment, you will need to port them to your local filesystem or Gadget editor and attempt to sync again. For example, I might port the changes from my Gadget editor over to my local filesystem, restart ggt sync, and notice ggt detects no conflicts and begins watching for file changes as normal.

Autmatically resolving conflicts 

If you always know which conflicting changes you want to keep, you can skip the prompt and automatically choose to keep your desired changes by using the --prefer flag:

Terminal
Shell
# automatically keep your local filesystem's conflicting changes
$ ggt sync --prefer=local
# automatically keep Gadget's conflicting changes
$ ggt sync --prefer=gadget

Syncing once 

If you want to sync your local filesystem with your Gadget environment once and not have ggt sync continue watching for changes, you can use the --once flag:

Terminal
Shell
$ ggt sync --once
→ Sent 12:00:00 PM
routes/GET.js updated ±
← Received 12:00:00 PM
routes/POST-order.js updated ±
Done!

The --once flag in combination with --prefer is useful if you want to run ggt sync in a script or CI/CD pipeline and ensure that the sync will not hang waiting for user input.

Terminal
Shell
$ ggt sync --once --prefer=local

Ignoring files 

Occasionally, you will want to prevent certain files from being sent to Gadget when you run ggt sync. For instance, you may have files that are only used for local development, such as .eslintrc, or an entire folder like .vscode.

To ignore these files, you can create a .ignore file in the root of your local directory.

.ignore
ignore
.eslintrc
.vscode

With that in place, ggt sync will no longer send those files up to Gadget when they're changed. The .ignore uses the same semantics as a .gitignore file. Take a look at their docs for more information.

The following files are always ignored whether or not you have an .ignore file

  • node_modules
  • .gadget
  • .git
  • .DS_STORE