Clasp on npm platform
Introduction
Official clasp README Badge
1
| [](https://www.npmjs.com/package/@google/clasp)
|
Clasp is a command line tool that allows you to develop Google Apps Script projects locally.
- With Clasp, you can:
- write code on your own computer and upload it to Apps Script when you’re done.
- download existing Apps Script projects so that you can edit them when you’re offline.
- Since the code is local, you can use your favorite development tools like
git when building Apps Script projects.
Code Structure
- clasp allows you to organize your code into directories, which are preserved when you upload them to script.google.com.
- For example:
1
2
3
4
5
6
7
8
9
| # On script.google.com:
├── tests/slides.gs
└── tests/sheets.gs
# Locally:
├── tests/
│ ├─ slides.gs
│ └─ sheets.gs
|
Installing Clasp
- Like any other Node.js package, you can install Clasp using
npm. - You can install it globally so that you can use it from any directory.
1
| npm install @google/clasp -g
|
Using Clasp
Logging in
- Before you can use Clasp, you need to log in to your Google account.
- This command logs in and authorizes management of your Google account’s Apps Script projects.
Terminal Message and SSH
- Once it is run, you are asked to sign into a Google account where your Apps Script projects are stored.
Browser Allow UI
- Once you allow access, a message is displayed on your local browser.
Logged-in message
Logging out
- If you want to log out of your Google account, you can use the following command.
Creating a new project
- You can create a new Apps Script project using the
create command. - Creates a new script project. Prompts the user for the script type if not specified.
Options
1
2
3
4
5
6
7
8
9
10
11
| clasp create
clasp create --type standalone (default)
clasp create --type docs
clasp create --type sheets
clasp create --type slides
clasp create --type forms
clasp create --type webapp
clasp create --type api
clasp create --title "My Script"
clasp create --rootDir ./dist
clasp create --parentId "1D_Gxyv*****************************NXO7o"cl
|
- These options can be combined.
1
| clasp create --title "My Script" --parentId "1D_Gxyv*****************************NXO7o" --rootDir ./dist
|
Clone an existing project
- You can clone an existing Apps Script project using the
clone command. - Clones a project from a
scriptId or URL to a local directory.
Options
scriptId | scriptURL: The script ID or script URL to clone.--versionNumber <number>: The version of the script to clone.--rootDir <dir>: Local directory in which clasp will store your project files. If not specified, clasp will default to the current directory.
1
2
3
| clasp clone "15ImUCpyi1Jsd8yF8Z6wey_7cw793CymWTLxOqwMka3P1CzE5hQun6qiC"
clasp clone "https://script.google.com/d/15ImUCpyi1Jsd8yF8Z6wey_7cw793CymWTLxOqwMka3P1CzE5hQun6qiC/edit"
clasp clone "15ImUCpyi1Jsd8yF8Z6wey_7cw793CymWTLxOqwMka3P1CzE5hQun6qiC" --rootDir ./src
|
Pulling changes
- You can pull changes from the Apps Script project using the
pull command. - Fetches an Apps Script project and saves it locally.
Pushing changes
- You can push changes to the Apps Script project using the
push command. - Updates an existing script project.
Note
- when you PULL from the browser editor, it will overwrite ALL local changes.
- when you PUSH to the browser editor, it will overwrite ALL remote changes.
Opening the project
- You can open the Apps Script project in the browser using the
open command.
Other Settings
The .claspignore file
- You can create a
.claspignore file in the root directory of your project. - Like
.gitignore, .claspignore allows you to ignore files that you do not wish to not upload on clasp push.
Add patterns to be excluded from clasp push.
- Note: The .claspignore patterns are applied by multimatch, which is different from .gitignore, especially for directories.
- To ignore a directory, use syntax like
**/node_modules/**. - Note: The
.claspignore patterns are applied relative from the rootDir.
- A sample
.claspignore ignoring everything except the appsscript.json and build/main.js:
1
2
3
| **/**
!build/main.js
!appsscript.json
|
- 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| # ignore all files…
**/**
# except the extensions…
!appsscript.json
!**/\*.gs
!**/_.js
!\*\*/_.ts
!\*_/_.html
# ignore even valid files if in…
.git/**
node_modules/**
|
.clasp.json file
- When running
clone or create, a file named .clasp.json is created in the current directory to describe clasp’s configuration for the current project. - Example .clasp.json:
1
2
3
4
5
6
7
| {
"scriptId": "",
"rootDir": "build/",
"projectId": "project-id-xxxxxxxxxxxxxxxxxxx",
"fileExtension": "ts",
"filePushOrder": ["file1.ts", "file2.ts"]
}
|
- Open script url.
- File > Project properties > Script ID
rootDir (optional)
- Specifies the local directory in which clasp will store your project files. If not specified, clasp will default to the current directory.
projectId (optional)
- Specifies the id of the Google Cloud Platform project that clasp will target. You must associate Google Script project with Google Cloud Platform beforehand.
- Run clasp open.
- Click Resources > Cloud Platform project….
- Specify the project ID project-id-xxxxxxxxxxxxxxxxxxx.
- Even if you do not set this manually, clasp will ask this via a prompt to you at the required time.
fileExtension (optional)
- Specifies the file extension for local script files in your Apps Script project.
filePushOrder (optional)
- Specifies the files that should be pushed first, useful for scripts that rely on order of execution. All other files are pushed after this list of files.
Pushing to GitHub
- You can push your Apps Script project to GitHub using the same commands you use for any other project.
- Remember to add the
.clasp.json and .claspignore files to your .gitignore file.
1
2
3
4
| # .gitignore
.clasp.json
.claspignore
|