Basic Concepts

Applets

An applet is made up of files that can import and export TypeScript modules, just like any other TypeScript project. Each applet is deployed to a working URL on Zipper's run domain: zipper.run.

Every applet requires a main.ts file that exports a function named handler. This handler function defines the behavior of the applet at its URL.

Since the applet above is named "greeting", the handler function in main.ts would be responsible for the behavior of https://greeting.zipper.run.

When you click ▷ Run, the applet outputs the following results:

Handler function

Handler functions only need to deal with the business logic of your task. Zipper will handle all the inputs and outputs.

Inputs

Your applet can take inputs if you write your handler function to accept arguments. Based on those argument types, Zipper will generate a UI form so that applet users can supply the input values. For example, let's modify the handler function in applet to accept a string called name.

The updated applet now includes a form field for users to input a name.

For more details on how to work with inputs, see the Accepting Inputs section.

Output

Your handler function can output more than just strings—objects, arrays, arrays of objects, and even HTML. Zipper formats the output to be pretty and human readable, and it even includes some basic pre-built UI components to make your applet more powerful. For more on working with outputs, see the Customizing Output section.

Context

Through the handler's context object, you have access to special information about the applet or the specific run. This object is passed as the second argument to the handler function. To make it easy and safe to see what you might have in the context argument, you can use the Zipper.HandlerContext type.

For example, let’s say you wanted to see if someone is signed into Zipper when they run your applet, and you want to use their email instead of the name input they passed. In this case, you would look for context.userInfo for contextual information about the user running the applet.

If you were logged in as "Bruce" from "Wayne Co", then your output might look like this:

Running your applet

There are multiple ways that you can run your applet and supply your inputs:

Within the browser

• Visit the applet's URL in your browser. Manually supply the inputs, and then click ▷ Run.
• Visit the applet's URL in your browser with query parameters appended: https://greeting.zipper.run/?name=Earth. This will pre-fill your form, but it will not run your applet.

To /run (also known as the "run URL")

Your applet's "run URL" runs the applet in your browser immediately, without requiring the user to click ▷ Run. You can supply inputs through query parameters.

• Visit the applet's URL in your browser with /run and query parameters appended: https://greeting.zipper.run/run?name=Earth.

API calls

To /api

• Send a GET request to the applet's URL with /api and query parameters appended: curl -X GET https://greeting.zipper.run/api?name=Earth
• Send a POST request with a JSON payload to the applet's URL with /api appended: curl -X POST --header "Content-type:application/json" --data '{ "name": "Earth" }' https://greeting.zipper.run/api

The response to these requests will be a JSON object that includes applet run metadata. The applet output can be found in the response object's data field.

Example:

$ curl -X POST \
       --header "Content-type:application/json" \
       --data '{ "name":"Earth"}' \
       https://greeting.zipper.run/api
 
{
  "ok": true,
  "data": "Hello, Earth!",
  "__meta": {
    "request": {
      "executionId": "5c74d40c-b4df-41ae-900c-3eaebb9a1d65",
      "server": "deno/aws-us-west-1",
      "timing": "system;dur=0,deployment;dur=1"
    }
  }
}

To /raw

• Send a GET request to the applet's URL with /raw and query parameters appended: curl -X GET https://greeting.zipper.run/raw?name=Earth
• Send a POST request with a JSON payload to the applet's URL with /raw appended: curl -X POST --header "Content-type:application/json" --data '{ "name": "Earth" }' https://greeting.zipper.run/raw

The response to these requests will the actual function response data (without any applet run metadata).

Example:

$ curl -X POST \
       --header "Content-type:application/json" \
       --data '{ "name":"Earth"}' \
       https://greeting.zipper.run/raw

Hello, Earth!

For more detailed information on working with HTTP requests, see the API Endpoints section.

Paths

main.ts is not the only file in your applet that can export a handler function. You can create other paths for your applet by adding new files that export their own handler functions. For example, let's say that you wanted to create a new path at https://greeting.zipper.run/salutations. To do this, create a file called salutations.ts file (the path will match everything before the .ts in the filename) that exports a function name handler.

Paths can be run independently, so you can test each function individually.

Note on path names

Because of Zipper's special usage of the /run, /api, and /raw paths (see Running your applet), avoid naming files in your project with these names, as they will be ignored.

Library files

Files you create are not required to export a handler function. This will make it a library file, which you can use to share code throughout your applet like a typical TypeScript module.

Config

Your files can also export a config object that customizes the in-browser run of your applet. For example, if you’d like your handler function to run when a user loads the page (instead of requiring them to supply inputs and click ▷ Run), you would do this:

Since it’s set to run: true and we’ve provided a defaultValue for name, the applet will run immediately upon visit.

For more details, see the Config section.