Develop Google Apps Script Code in Your Local Code Editor

Back around 2016/2017, I was working almost exclusively with Google Sheets, and Apps Script, to do analytics and reporting for the department I was working in.

I was using Google’s in-browser editor in Google Sheets to write my Apps Script code, as that was the only way to do it at the time. Now I’m not saying Google’s in-browser editor is terrible, but it definitely leaves a lot to be desired, and it made me really wish I could write my Apps Script code in a proper code editor like VS Code.

Well, fast forward about 7 years or so, and I only just now found out it’s possible to do so! Seems that not long after I had first searched for the ability, Google released a command line tool named clasp that allows you to develop your Apps Script code locally in VS Code (and probably other editors as well, although I haven’t personally tried any others), and then push your code to Google’s servers when you’re ready to run it.

The beauty is that since you’re developing your code locally, you can take advantage of the features of a proper code editor, like syntax highlighting, code completion, etc. You can also use Git to version control your code, and npm/yarn/pnpm to manage your dependencies!

So without further ado, here’s how you can set up your environment to develop Google Apps Script locally in Visual Studio Code (or your favourite code editor)…

Setting Up Your Environment

1. Install Node.js

First off you’ll need to have Node.js installed, as clasp requires it to run. So if you don’t have it already, download it from the Node.js website and install it on your machine.

If you have Node.js already installed, just make sure it’s version 4.7.4 or later. Basically, with Node LTS (as of me writing this) at v20.11.0, if you’ve installed Node.js within the last century or so, you should be good to go. 🤪

2. Install clasp

Once you have Node.js installed, you can install clasp globally by running the following command in your terminal:

npm install -g @google/clasp

Note: You can view the npm package info and basic documentation at npmjs.com/package/@google/clasp

Now I’m personally more of a Yarn guy myself, but because the newer versions of Yarn no longer support global installs, you’ll have to use npm to install clasp globally.

Don’t worry though … If you’re a Yarn person like me, you can still use Yarn (or pnpm if that’s your thing) to manage your project’s dependencies, you only need npm to do the initial global clasp install.

3. Enable the Google Apps Script API

Next, you’ll need to enable the Google Apps Script API for your Google account. You can do this by visiting the Google Apps Script API settings and flipping the toggle to the “On” position.

4. Log in to Google

Next, you’ll need to log in to your Google account (the one you’d be using to create your Google docs/sheets/etc.) using clasp. You can do this by running the following command in your terminal:

clasp login

After running the login command, a browser window will open asking you to log in to your Google account.

Once that’s done, if the browser window is still open, you can go ahead and close it and return to your terminal.

5. Initialize Your Project in Git (Optional)

If you’re using Git to version control your code, you can now initialize your project as you would any other project, as such:

git init

6. Add the GAS Code Completion Library (Optional)

If you want to take advantage of code completion for Google Apps Script in your editor, install the library by running the following command in your terminal:

yarn init
yarn add @types/google-apps-script

or, if using npm:

npm init
npm install @types/google-apps-script

Setting Up Your Google Apps Script Project

Now that the base environment is setup, you can do a number of things, but to start you’ll likely want to do one of two things:

1. Create a new Google Apps Script project

   or

2. Clone an existing Google Apps Script project

I generally start my spreadsheets in my browser first, in order to get a general sheet layout going before I start adding in any scripting, so we’ll look at that approach first.

Cloning an Existing Google Apps Script Project

In order to clone your GAS project, you’ll need either the script ID, or alternatively, you can simply use the entire script URL.

The script ID is the long string of characters in the script URL of your Google Apps Script project that comes after https://script.google.com/u/0/home/projects/ and before /edit.

ex:

https://script.google.com/u/0/home/projects/1G*****************************gJ/edit

To clone the project, run the following command in your terminal:

clasp clone <script-id>

or

clasp clone <url>

You can specify the directory name you want to clone the project into by adding it to the end of the command using the --rootDir flag. Otherwise the project will simply be cloned into the current directory.

Results

After running the clone command, you should see output similar to the following:

wheresbaldo testing % clasp clone "https://script.google.com/u/0/home/projects/1V*****************************7L/edit"
⠋ Cloning files…
Warning: files in subfolder are not accounted for unless you set a '/Users/wheresbaldo/dev/apps_script/testing/.claspignore' file.
Cloned 2 files.
└─ /Users/wheresbaldo/dev/apps_script/testing/Code.js
└─ /Users/wheresbaldo/dev/apps_script/testing/appsscript.json
Not ignored files:
└─ /Users/wheresbaldo/dev/apps_script/testing/appsscript.json
└─ /Users/wheresbaldo/dev/apps_script/testing/Code.js

Ignored files:
└─ /Users/wheresbaldo/dev/apps_script/testing/.clasp.json

Creating a New Google Apps Script Project

Clasp also allows you to create a new Google Apps Script project from the command line. When you create a new project this way, you can create it as a standalone project (i.e: not bound to any doc/spreadsheet/etc.), or you can bind it to an existing one.

To create a new project bound to an existing doc or sheet, run the clasp create command in your terminal, supplying the --parentId flag with the ID of the doc/spreadsheet/etc. you want to bind the project to, for example:

clasp create --parentId <doc-id>

If you want to create a standalone project, simply run the clasp create command without the --parentId flag.

Results

After running the create command, you should see output similar to the following:

wheresbaldo testing % clasp create --title "My Test Script" --parentId "1x*****************************1w"
Created new  script: https://script.google.com/d/1C*****************************mO/edit
Warning: files in subfolder are not accounted for unless you set a '/Users/wheresbaldo/dev/apps_script/testing/.claspignore' file.
Cloned 1 file.
└─ /Users/wheresbaldo/dev/apps_script/testing/appsscript.json

Note: In the above example, I’ve also added the --title flag to specify the title of the project. If you don’t specify a title, the project will be created with the default title “Untitled”.

A cool thing to note: if you create a new script using the create command, you can open the script in your browser right from the command line by running the clasp open, like such:

clasp open "1C*****************************mO"

Developing Your Google Apps Script Code

Ok, so we set up our base environment, we then created/cloned a script project, and now we’re ready to start developing our code!

Now, I won’t bother going into specifics about writing Apps Script code, as I’m going to assume you already know how to do that. But once you’ve got some code written/updated, you’re going to want to push it to Google’s servers, similar to how you would push code to a remote repository in Git, although quite a bit simpler:

clasp push

Yup, that’s it! Just run the clasp push command in your terminal, and your code will be pushed to Google’s servers.

Now unlike Git, clasp doesn’t have a concept of branches, or committing only specific files to the push. When you run clasp push, it pushes all the files in your project to Google’s servers, overwriting any existing files on the target project.

If you have files you don’t want it to push, you can add them to the .claspignore file in your project’s root directory, and clasp will ignore them when you run the push command.

That said, you may not even need a .claspignore file, as per the clasp documentation:

If no .claspignore is specified, a default set of patterns is applied. This default set will only consider the appsscript.json manifest and any JavaScript, TypeScript and .html source files within the rootDir folder. Child folders other than .git and node_modules are processed.

---

And that pretty much covers the basics of how you can develop your Google Apps Script code locally!

Further Info

TypeScript Support

Clasp supports coding in TypeScript, although if you go that route, you’ll be unable to edit your code in the Google Apps Script editor (which probably isn’t a big deal), as it only supports JavaScript. However, I believe at that point, you also wouldn’t be able to use the clasp pull command, as it would be pulling the transpiled GAS code, not TypeScript.

But if you’re using clasp, I think part of the point is to use a CVS like Git, in which case you’d do your pulls and merges in Git, and then push the code to Google’s servers when you’re ready to run it, so it’s maybe not a huge deal.

Full details, including the “gotchas” of using TypeScript with clasp (there are a lot), can be found in the clasp Github documentation.

Other clasp Commands

For the full list of options for clasp, you can refer to the clasp developers guide, or for more detailed information, checkout the clasp Github reference.

Final Thoughts

I’m really glad Google decided to release a method to develop GAS code locally. It makes the developer experience so much better; I just wish I’d found out about it sooner!

Even with the TypeScript gotchas, and the overwriting of all files on pushes, I still think it’s a great tool, and I’m looking forward to using it exclusively for any Apps Script code I need to write in the future.