You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**A modern development environment for building Google Apps Script projects with modern web development tools.**
8
+
9
+
This starter kit provides a boilerplate for developing Google Apps Script projects using modern JavaScript (ES6+) and a local development environment. It includes a curated selection of tools to enhance your development workflow, including code bundling, linting, testing, and deployment.
2
10
3
11
4
12
@@ -8,103 +16,138 @@ You can build Google Workspace add-ons (for Google Docs, Slides, Gmail and Googl
8
16
9
17
The starter kit is used by [Digital Inspiration](https://digitalinspiration.com/) for building popular Google add-ons including [Gmail Mail Merge](https://workspace.google.com/marketplace/app/mail_merge_with_attachments/223404411203), [Google Forms Notifications](https://workspace.google.com/marketplace/app/email_notifications_for_google_forms/984866591130) and [Document Studio](https://workspace.google.com/marketplace/app/document_studio/429444628321).
10
18
11
-
## Build with Google Apps Script 🚀
12
-
13
-
Setting up a modern development environment for building [Google Apps Script](https://www.labnol.org/topic/google-apps-script/) projects is easy and quick (**[video tutorial](https://www.youtube.com/watch?v=KxdCIbeO4Uk)**).
19
+
## What's Included
14
20
15
-
You also need to install Node.js which includes the npm package manager.
21
+
This starter kit comes with a pre-configured set of tools to help you write high-quality Google Apps Script code:
16
22
17
-
### :package: Getting Started
23
+
-**[Vite](https://vitejs.dev/):** A next-generation build tool that provides a fast and lean development experience.
24
+
-**[Jest](https://jestjs.io/):** A delightful JavaScript testing framework with a focus on simplicity.
25
+
-**[ESLint](https://eslint.org/):** A pluggable and configurable linter tool for identifying and reporting on patterns in JavaScript.
26
+
-**[Prettier](https://prettier.io/):** An opinionated code formatter that enforces a consistent style.
27
+
-**[clasp](https://github.com/google/clasp):** The official command-line tool for managing Google Apps Script projects.
18
28
19
-
**1.** Clone the repository and install npm dependencies and [utilities](TOOLS.md).
29
+
## Getting Started
20
30
21
-
```
22
-
npx degit labnol/apps-script-starter my-project
23
-
cd my-project
24
-
npm install
25
-
```
31
+
Follow these steps to get your development environment set up and running.
26
32
27
-
**2.** Log in to Google clasp and authorize using your Google account.
33
+
### Prerequisites
28
34
29
-
```
30
-
npx clasp login
31
-
```
35
+
Before you begin, ensure you have the following installed on your system:
32
36
33
-
**3.** Create a new Google Script bound to a Google Sheet (or set the type as standalone to create a standalone script in your Google Drive)
37
+
-[Node.js](https://nodejs.org/) (which includes npm)
**4.** Include the necessary [OAuth Scopes](./scopes.md) in the [appsscript.json](./appsscript.json) file
42
+
1.**Clone the repository:**
40
43
41
-
**5.** Deploy the project
44
+
```bash
45
+
npx degit labnol/apps-script-starter my-project
46
+
cd my-project
47
+
```
42
48
43
-
```
44
-
npm run deploy
45
-
```
49
+
2. **Install dependencies:**
46
50
47
-
The `dist` directory contains the bundled code that is pushed to Google Apps Script.
51
+
```bash
52
+
npm install
53
+
```
48
54
49
-
55
+
3. **Log in to clasp:**
50
56
51
-
### The .claspignore file
57
+
Authorize `clasp` to manage your Google Apps Script projects using your Google account.
52
58
53
-
The `.claspignore` file allows you to specify file and directories that you do not wish to upload to your Google Apps Script project via `clasp push`.
59
+
```bash
60
+
npx clasp login
61
+
```
54
62
55
-
The default `.claspignore` file in the Apps Script Starter kit will push all the JS and HTML inside the `rootDir` folder and ignore all the other files.
63
+
4. **Create a new Google Apps Script project:**
56
64
57
-
## :beginner: Using Git with Google Apps Script
65
+
Create a new script project bound to a Google Sheet or as a standalone script.
Create a new repository in Github and make a note of the URL of the new repository. Next, open the terminal and run the above commands to push your Apps Script project to Github.
71
+
This will create a new Google Sheet and a bound script project inyour Google Drive.
62
72
63
-
## Custom Google Sheet functions
73
+
## Development
64
74
65
-
Please read [the tutorial](./FUNCTIONS.md) on how to write custom functions for Google Sheets using Apps Script.
75
+
This starter kit provides a streamlined development workflow to help you build your Google Apps Script projects efficiently.
66
76
67
-
##Testing your Google Apps Script code
77
+
### Development Server
68
78
69
-
You can run tests with jest using
79
+
To start the development server, run the following command:
70
80
81
+
```bash
82
+
npm run dev
71
83
```
84
+
85
+
This command will watch forchangesin your source files and automatically rebuild the project.
86
+
87
+
### Code Structure
88
+
89
+
The main source code foryour application is locatedin the `src` directory.
90
+
91
+
- `src/index.js`: The main entry point for your application.
92
+
- `src/html/`: Contains the HTML files for your user interface.
93
+
- `src/server/`: Contains the server-side code for your application.
94
+
95
+
### Writing Code
96
+
97
+
You can write your code using modern JavaScript (ES6+) features. Vite will automatically transpile your code to a format that is compatible with the Google Apps Script V8 runtime.
98
+
99
+
## Testing
100
+
101
+
This starter kit uses [Jest](https://jestjs.io/) for unit testing.
102
+
103
+
### Running Tests
104
+
105
+
To run the tests, use the following command:
106
+
107
+
```bash
72
108
npm run test
73
109
```
74
110
75
-
This has limitations:
111
+
### Writing Tests
76
112
77
-
-You _can_ test code that has no dependencies to Google App Script code, e.g.
113
+
You can write tests foryour codein files with a `.test.js` extension. The tests are located alongside the files they are testing.
**Note:** You cannot directly test code that has dependencies on Google Apps Script services (e.g., `SpreadsheetApp`, `Logger`). You will need to mock these services in your tests.
81
116
82
-
```
117
+
## Deployment
83
118
84
-
- You _can not_ test code that has dependencies to Google App Script code, e.g.
119
+
To deploy your project to Google Apps Script, run the following command:
85
120
121
+
```bash
122
+
npm run deploy
86
123
```
87
-
function notTestable() {
88
-
Logger.log("notTestable"); // <-- Google Apps Script function. Not callable in dev
89
-
SpreadsheetApp.getUi(); // <-- Google Apps Script function. Not callable in dev
90
-
...
91
-
}
92
-
```
93
124
94
-
Check out [jest 'expects' here](https://jestjs.io/docs/expect)
125
+
This command will build your project and then use `clasp` to push the bundled code to your Google Apps Script project.
126
+
127
+
## Configuration
128
+
129
+
The starter kit includes several configuration files to customize the development environment:
130
+
131
+
- **`appsscript.json`:** The manifest file for your Google Apps Script project. You can use this file to specify dependencies, OAuth scopes, and other settings.
132
+
- **`.clasp.json`:** The configuration file for`clasp`. This file specifies the `scriptId` and `rootDir`for your project.
133
+
- **`vite.config.js`:** The configuration file for Vite. You can use this file to customize the build process.
134
+
- **`.prettierrc`:** The configuration file for Prettier. You can use this file to customize the code formatting rules.
135
+
- **`eslint.config.js`:** The configuration file for ESLint. You can use this file to customize the linting rules.
Contributions, issues, and feature requests are welcome. If you are using this starter kit and have fixed a bug for yourself, please consider submitting a pull request!
99
140
100
-
[Amit Agarwal](https://www.labnol.org/about) is a web geek, Google Developers Expert (Google Workspace, Google Apps Script), Google Cloud Innovator, and author of [labnol.org](https://www.labnol.org/), a popular tech how-to website.
141
+
## Development Conventions
101
142
102
-
He frequently uses [Google Apps Script](https://www.labnol.org/topic/google-apps-script/) to automate workflows and enhance productivity. Reach him on [Twitter](https://twitter.com/labnol) or email `amit@labnol.org`
143
+
- **Coding Style:** The project uses Prettier forcode formatting and ESLint for linting. The configuration for these tools can be foundin`.prettierrc` and `eslint.config.js` respectively.
144
+
- **Testing:** The project uses Jest for unit testing. Test files are located alongside the files they are testing and have a `.test.js` extension.
145
+
- **Commits:** The project does not have a formal commit message convention, but it is recommended to follow standard practices for writing clear and descriptive commit messages.
103
146
104
-
### :cherry_blossom: Contribution
147
+
## License
105
148
106
-
Contributions and feature requests are welcome. If you are using the Google Apps Script starter package and fixed a bug for yourself, please consider submitting a PR!
149
+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file fordetails.
0 commit comments