Google Apps Script, clasp, Visual Studio Code, Node.js, npm, Windows 10: Updated 23 Oct 21
Table of Contents
I don’t mind the Google Apps Script built-in online editor. It provides word completion, error handling, and pretty formatting, making it ideal to hash out a small automation project pretty quickly.
However, one of its major limitations is that after 1,000 or so lines of code and multiple files, it can start to get a little clunky. It also makes things a bit difficult when you want to use your own debugging or testing software. Further, if you have a HTML (CSS, JS) intensive app, it is quite hard to create and test the front end. Finally, it can be just damn comfortable slipping on a pair of your favourite slippers and using your preferred Text Editor or IDE.
This little tutorial is going to guide us through the steps that will allow us to work, push and pull Google Apps Script code from the online editor to Visual Studio Code. We’ll even be able to run the program from the terminal in VS Code and manage versions.
Fortunately, Google developed a tool that enables us to develop Google Apps Script code from the command line, clasp.
Setup Visual Studio Code for Google Apps Script
The steps to setting up Visual Studio for Google Apps Script production are as follows:
- Install clasp via npm.
- Give permission to run the Apps Script API.
- Get text completion for Apps Script
Installing clasp
clasp is a command-line tool that allows you to connect with your Google Apps Script files to:
- Pull them from the cloud.
- Push them from your PC to the cloud.
- Review and set versions.
- Open the Google Apps Script project on the online editor.
There are a few other tasks that clasp achieves but these are the ones I think you are going to use the most.
clasp is run in node.js via npm. You will need to install a recent version of Node.js that is 6.0.0 or later.
Note: I’ll be focussing on a Windows 10 install.
Right-click and run your preferred command-line interpreter as administrator (I’m using Powershell for Windows) enter the following:
|
1 |
npm i @google/clasp -g |
The above command invokes npm instructing it that it will install (i)and then gets clasp from the Google repository. It then ensures that clasp will be installed over the entire system, or globally (-g).
To test to see if clasp is working, you can now type clasp into the command line. You should see a list of command option if all is working.
Next, type login. This will set you up login for the first time.
|
1 |
clasp login |
A browsers window will appear prompting you to log into your chosen account.
Once you select your account. Another window will appear with a crazy-long list of permissions that you need to allow.
You will then get a confirmation if all goes well:
|
1 |
Logged in! You may close this page. |
One final little job you will need to do is to go into your Google Apps Script Settings and toggle the API to, on.
Running Google Apps Script in Visual Studio Code
Open Visual Studio Code. Navigate to your usual programming or practice folder. You and create a new folder for your Google Apps Script project here or you can do it from the command line.
You can run command-line prompts from your preferred interpreter inside Visual Studio Code by going to the Terminal menu and selecting New Terminal or Ctrl + Shift + `.
Setup Google Apps Script Word Completion in Visual Studio Code
Before we get cracking with playing around will Clasp, let’s make sure Visual Studio Code is set up to be able to autocomplete Google Apps Script classes and methods.
On the command line in your Visual Studio Code project, type:
|
1 |
npm install --save @types/google-apps-script |
Note: The types package for Google Apps Script is generally designed to be loaded locally. Meaning withing the project. One workaround for a global install can be found in this StackOverflow question by Aaron Dunigan AtLee.
clasp create
Go into your new folder. To connect your project with clasp type:
...\GoogleAppsScript\clasp_test>clasp create
You will be prompted with an option of which type of script you wish to choose, for example, standalone, spreadsheet document, slide, etc. You can use the arrow keys to select the one you want. For our example, we will just run a standalone script. Click <enter>.
clasp will create the project on your script.google.com dashboard and also save two JSON files into your new clasp_test directory.
It’s probably a good idea to make a copy of the URL to the script.
Note! When a script is created using clasp it set the timezone inside the appsscript.json to “America/New_York” rather than your actual timezone. If I were to create the same script from script.google.com the timeZone would have read my current location of “Australia/Hobart”.
*.gs files = *.js files
When we normally create a Google Apps Script file, we usually have two options the .gs file for Google Script server-side code and the .html for client-side code.
clasp expects you to run .js files from your pc and will upload and convert the file to .gs when you push it to the cloud and reverse the process when you pull it to your computer.
Go ahead and make a simple “Hello, World” program that we can log. Give it a file name test.js and add the following code. Try typing it in and you should see that autocomplete is working.
|
1 2 3 4 |
function runTet() { Logger.log("Hello, world!"); } |
Note! If you don’t see the Google Apps Script Autocomplete, first try and reinstall @types/google-apps-script again. If you have no luck, try some of the options in this post.
clasp push
Great, we created our file. Let’s go and push it to our cloud script.google.com.
clasp push
You will be returned the following:
|
1 2 3 4 |
...Coding Practice\GoogleAppsScript\clasp_test> clasp push └─ appsscript.json └─ test.js Pushed 2 files. |
Note! If you already have your project open in the online Google Apps Script IDE, you will need to refresh the page to see the changes.
clasp open
If we want to see our script on the Google Apps Script code editor in your browser, you can type:
|
1 |
clasp open |
This will open your project online:
You can see that the test.js file has been converted to test.gs during the push.
Let’s go ahead and make a few changes to our code on our online editor. We can see that we made a few mistakes in our code. Let’s change the function name to runTest and remove line 3. We’ll also go ahead update our log to something more pure, some more honest…
|
1 |
Logger.log("Hello, You handsome coding goat!"); |
Also, let’s add a *.gs file called, creatively, newFile.gs. Then somewhat assertively add the following code:
|
1 2 3 |
function myFunction() { console.log("Pull This!!!") } |
Go ahead and save that in your browser text editor, then head back to the Visual Studio Code terminal.
clasp pull
In Visual Studio Code, type:
|
1 |
clasp pull |
This will grab the code from the browser text editor and update your local files on your computer.
Now that we have updated our runTest.gs file it will look like this in Visual Studio Code.
Note the italicised newFile.gs. This indicates that it has not yet been saved. Click the file to save it.
Updating Versions
You can also manage version control from clasp. This is particularly important for creating webApps and Add-on projects.
To create a version type:
|
1 |
clasp version "[the name of your version]" |
This will return the version number, but not the description you created. To see the description you can view all versions.
To see your versions, you can type:
|
1 |
clasp versions |
This will result in something like:
|
1 2 3 |
~ 2 Versions ~ 2 - The Handsome Update 1 - Update 1 |
You can also pull a project by version number.
|
1 |
clasp pull --versionNumber 2 |
Clone
You can also make a copy or clone your project.
Open a new window in Visual Studio Code (Ctrl + shift + n). Create a new directory and open the terminal. We’ll call ours, clasp_test2.
You will need either the URL or the script id. The fastest way for me to find the script id was to go back to the original clasp_test window in Visual Studio Code and open the clasp.json file and copy the scriptId. You could just as easily grab the URL from going to your script in your browser or typing clasp list to get a list of your recent projects and copying the appropriate URL. -version as well.
Back in your clasp_test2 window on Visual Studio Code, type into the terminal:
|
1 |
...\GoogleAppsScript\clasp_test2> clasp clone "your Google Apps Script project ID" |
This will create a copy of your project in your new directory. This will still reference the same project id as your other project and any changes will influence your other clones.
TypeScript ( *.ts) anyone?
You can create TypeScript files and they will be compiled to a Google Script (*.gs) file.
Google Apps Script text completion and hints will work with TypeScript too.
Go on. Give it a go!
|
1 2 3 |
function newTest() { Session.getActiveUserLocale(); } |
|
1 |
clasp push |
When your TypeScript file is pushed to Google Apps Script it will be compiled with ts2gas which is packaged with clasp.
You will also get a comment at the top of your file in the Google Apps Script IDE.
TypeScript pull…Warning
If you pull a file from the online IDE that was created in TypeScript, the file will be saved as a JavaScript file, unfortunately.
Not being a TypeScript user, I am not sure if there is a workaround for this. Let me know in the comments below if there is and I will add it to the guide.
Conclusion
That’s the basics. You can explore more about Clasp by going to their GitHub page. If you want to automate some of these processes – like have the push and pull automated – you can use tools like grunt and gulp to make your life easier.
So, do you prefer working in Visual Studio Code over Google Apps Scripts online Text Editor? Was it worth the effort to set it all up? Let me know in the comments below.
If you have found the tutorial helpful, why not shout me a coffee ☕? I'd really appreciate it.
Need help with Google Workspace development?
My team of experts can help you with all of your needs, from custom app development to integrations and security. We have a proven track record of success in helping businesses of all sizes get the most out of Google Workspace.
Schedule a free consultation today to discuss your needs and get started or learn more about our services here.
~Yagi
absolutely worth the effort. many thanks!
This was definitely worth the effort. Thanks for the easy to follow tutorial.
Thanks Paul,
I’m glad you found it useful.
I saw a lot of tutorials on this subject, they instruct you to do a lot of unnecessary stuff claiming that their way is the bare minimum. This tutorial is the simplest best one I’ve read so far, thanks for the time you took doing it.
Hi Oshio,
Thanks for the kind words.
~Yagi
This is very helpful. Thank you! I’d love to see a writeup on how to configure VS Code to auto push on save. Is that possible?
Thanks for the kind words.
Good idea. I will add it to my list of tutorials.
~Yagi
I look forward to it. Where can I follow the next posts?
Super helpful! Thank you!!
You’re welcome, David!
Thanks for this! The only place I got a bit stuck was in how to turn on API access in my apps script settings. For those of you who are curious as well, go to: https://script.google.com/u/2/home/usersettings
¡Una belleza! Ya quería usar un editor mejor que el online. Cuando hacía búsquedas la ventana llenaba mi pantalla de 15″. Ahora si disfrutaré programando en GAS. Muchas, muchas gracias.
A beauty! I already wanted to use a better editor than the online one. When I was doing searches, the window filled my 15″ screen. Now I will enjoy programming in GAS. Thank you very much. Greetings from La Paz, Bolivia.
You’re welcome, Ricardo.
Very useful, thank you! I had set this up before but lost that link to setup my new MacBook (works just fine on MacOS by the way).
Great to hear, Rhodes!
Hi rhowes, great to hear!
Amazing.
Are you teacher in UDEMY?
I need one solution in my script.
Hi Eduardo,
Thanks for the kind words.
No, I don’t teach on Udemy. Unfortunately, I am pretty busy at the moment, however, many of my readers have used Fiverr with great success in hiring a Google Apps Script coder to create a small app or help to provide a solution to your Google Suite needs.
Here is the link to Fiverr below one is an affiliate link that helps me earn a little money to upkeep this site. The other is a direct link. The affiliate link does not cost you any extra if you want to support me:
Fiverr ( My affiliate link)
Fiverr
Cheers,
Yagi
Wish that it worked for me, but the type ahead lookups don’t work. Is this normal?
$ npm install –save @types/google-apps-script
npm WARN saveError ENOENT: no such file or directory, open ‘/Users/…Apps Script/package.json’
npm WARN enoent ENOENT: no such file or directory, open ‘/Users/…/Apps Script/package.json’
npm WARN Apps Script No description
npm WARN Apps Script No repository field.
npm WARN Apps Script No README data
npm WARN Apps Script No license field.
@types/google-apps-script@1.0.10
updated 1 package and audited 1 package in 1.269s
found 0 vulnerabilities
Just to follow up, after creating a new folder it worked. Not sure why it wasn’t working in the other folder. Anyway, thanks for the article, very helpful!
Hi Michael,
Glad you got it working.
Cheers,
Yagi
Hi Michael,
Try typing:
npm init
Before:
$ npm install –save @types/google-apps-script
Very useful! Thank you!
I just started working with Google Script and your tutorials have been so helpful! I crashed my OS yesterday trying to install Clasp using unnecessarily complex instructions. This time it went smooth as silk. Thanks!
That’s really great to hear, mate. It’s really heartening.
Yes, this was definitely worth it. Much better syntax highlighting and intellisense! Dark theme, and the workbench where all my tools are. Thank you for the very short and straight to the point tutorial. Everything is working even though I did get some errors when installing clasp “requires a peer of inquirer@^5.0.0 || ^6.0.0 but none is installed. You must install peer dependencies yourself.”
That said, it doesn’t seem to be causing any issues so not sure what’s going on there. As my dear old Paw always said, “Boy, if it ain’t broke’r Chinese then it don’t need fixin’.” Guess that means that until it stops working I’ll use it as is.
Really helpful. Thank you!
p.s. Not sure if anyone else is seeing this, but “>” is showing up as “>” in some of the examples above.
Dear Yagi,
Thanks for the fantastic tutorial.
I run into a minor problem and I appreciate your insight. If I just run the command clasp login, go to the browser window, select my account, give my permissions etc, I just get an error warning: Can’t establish a connection to the server at localhost:53778.
If I add the options class login –no-localhost, it works.
Do you happen to know why?
undoubtedly, this one is the best tutorial available online.
Beside that, i have one question, and it is that,
I want to debug my code in visual studio code itself, instead of pushing the code to google server and then execute there..
So that, i can avoid these unnecessary push and pull steps…
Is it anyhow possible ?
Thanks,
Rohit
Hi
Great tutorial!
Although I’m struggling with $ npm install –save @types/google-apps-script , I’m having the same problem as Michael.
The only way I got it to relatively work was coding in typescript instead of GAS, and I’m not interested on that.
Any idea of what is failing?
Thanks
very good!thanks bro
You’re welcome.
This is very good ! Thanks a lot.
A question though: when pushing data, the /dev entry point to my webapp (https://script.google.com/macros/s/%5BmyScriptID%5D/dev) is broken, which sucks as I use that a lot.
Apparently this is a know issue with clasp (see https://github.com/google/clasp/issues/63#issuecomment-647987630).
Have you found any way to work around this ? I still have a lot of dev to do before deploying so that /dev is a must for me at this point…
Appreciate any pointer.
Hi zedug,
Yeah. I’ve come across that too. I haven’t found a workaround yet. I recall that here was a reported bug, but I can’t seem to find it.
I don’t often use CLASP too much lately (probably abandoned it for the same reason). The new IDE is so much better for front-end work now though and there is a push for GIT integration.
Sorry, I couldn’t help you there.
~Yagi
Just to confirm, can the project now be run and debugged inside VS Code?
Hi BlueNun,
Using this approach you can write your Apps Script in Visual Studio Code then push and pull the code to the Google Apps Script IDE with CLASP. You can find out more on what it does here: CLASP Command Line Interface.
There are also plugins available in Visual Studio Code like the one mentioned in the post to autocomplete your text.
There is also a recent update to the world of app development and Google Add-ons where you can now use alternative runtimes (read, different coding languages). Here is Developer Advocate Charles Maxons’ recent post on it:
– https://developers.googleblog.com/2021/03/evolving-google-workspace-add-ons-with.html
And a link to the docs:
– The docs
Hope this helps,
~Yagi
Really useful, thank you for detailing the setup process.
You’re welcome.
Hi Yagi,
have you ever come across the issue in this StackOverlow question relating to vscode syntax highlighting scriptlets? It’s one of those things that I really bugs me & I want to try and solve…I spent x2 days looking at eslint’ing, but I think it was a ‘Rabbit Hole’
https://stackoverflow.com/questions/56238534/make-vscode-syntax-highlighting-accept-google-apps-script-scriptlets
Hi m1ck5k1,
I see what you mean by a ‘rabbit hole’. I put about five hours into it this afternoon with no success but some good clues. Here’s what I found:
It looks like we would have to build vscode extension and make use of the language configuration point – specifically the brackets. This gitHub example was pretty good.
From there, I don’t really know. I’m not sure how to allow the extension to be added to HTML in a workbook. I am sure there is a way.
Hopefully, I will get another chance to revisit this.
~Yagi.
Hey!
Thanks for the good description!
Can anyone come across:
Made a clasp pull of the working code in VSCode.
VSCode sees methods from ‘adjacent’ files, switches to them, but does not start – Uncaught ReferenceError: MethodName is not defined.
Read about export.module
Improved package.json
Attributed export to the necessary methods In the necessary file,
entered import.
OK! Debugging started.
But now when clasp push VScode writes: SyntaxError: Cannot use import statement outside a module line:1 (in this import line)
I have a few .js files in a project. They call functions from each other. VS code is giving me an error if a function is not in the same file. How do you tackle this with this approach?
Does this occur when you push the script to the IDE and run it?