Introduction
The Quip Live Apps API enables developers to extend the Quip document canvas with interactive, custom components. The goal of the platform is to expand the scope and capabilities of Quip's living documents:
- Enable rich, visual forms of communication within documents
- Enable end users to transform documents into tools for custom and complex workflows
- Enable Quip documents to deeply integrate with third party services
Why Build on Quip?
We've spent years building a product that's changing the face of productivity and collaboration. Now, we're turning Quip into a platform where developers can integrate solutions directly into the Quip canvas. Apps work cross-platform and inherit collaboration and social features as well as notification and offline capabilities.
Getting Started
This tutorial will walk you through creating a Hello World app.
Prerequisites
- You must have a Quip account and be a member of a Quip site.
- Make sure you have Node >= v6 and NPM >= v3 installed.
- Run
npm install -g create-quip-app
in your terminal.
Depending on how you installed node you may need to run it as root with:
sudo npm install -g create-quip-app. - You need to flip a flag in your browser to allow self-signed certificates on localhost for HTTPS:
- In Chrome, copy this URL and open it in a new tab:
chrome://flags/#allow-insecure-localhost
Then click "Enable" and click the "Relaunch" button at the bottom of the page. - In Firefox and Safari, go to https://localhost:8888, then click "Advanced → Add Exception → Confirm Security Exception".
Create Your App
- First you need to create your app. Go to the Quip Developer Console and click "Create a Live App".
- Make note of your app ID.
- Run
create-quip-app my-app
in your terminal. This will create a directory calledmy-app
inside the current folder. Inside that directory, it will generate the initial project structure:my-app ├── package.json ├── node_modules ├── webpack.config.js ├── app │ └── manifest.json └── src └── App.less └── App.jsx └── root.jsx
- Run
cd my-app
in your terminal. - Open the file
app/manifest.json
in your editor. - Paste in your app ID.
- Give your app the name
Hello World
.
This is what users will see as the title of your app and the key they'll use to insert your app into their documents. - Save your changes to the
app/manifest.json
file.
Your app is now ready for deployment!
Deploy Your App
After this step, your app will be live in a Quip document.
- Make sure you are in the
my-app
directory. - Run
npm run build
in your terminal. - Click the "Upload app.ele" button in the Quip Developer Console.
- Choose the
app/app.ele
file then click the "Update" button.
You should now see "App deployed successfully" at the top of the page. - In a new browser tab, open quip.com and create a new document.
- Type
@Hello World
in the document (or @ followed by your app's name from app/manifest.json). You should see your app listed in the insert menu. - Hit ENTER to insert your app into the document.
- You should now see your app (with the text "Hello, world!") rendered into the Quip document!
Develop Your App
You've deployed your first app! The next step is iterating on your app locally to make it better. To do that, you're going to run a local webserver and connect your document's app to it. Then, you can edit your code and just reload your app to pick up changes.
- Run
npm start
in your terminal in yourmy-app
directory.- Run this command whenever you work on your app, then leave it running continuously — it will automatically watch for code changes and update the compiled files as you edit.
- If you have a syntax error in your code, it will show up here.
This uses webpack to compile your .js/.jsx and .less files into a single .js file and .css file in my-app/app/dist.
- In your Quip document, focus your app by clicking on it. Your app's "Hello World" menu button will appear. Click "Hello World → Use Local Resources" in the Developer section of that menu.
This will save a setting so that your app will load the code from the local server you're running with npm start on https://localhost:8888/. - Now, reloading your app via "Hello World → Reload" will pick up any local changes you make without requiring you to upload a new
app.ele
to Quip!- Note if you make any changes to the
manifest.json
file, you will need to re-runnpm run build
and then upload yourapp.ele
file to get those updates.
- Note if you make any changes to the
- Now open
my-app/src/App.jsx
in your editor, find the text "Hello, world!", and change it to something else:import Styles from "./App.less"; export default class App extends React.Component { render() { return <div className={Styles.hello}>YES it worked!</div>; } }
- Click Reload again from your app's menu button and your new text should appear! Not seeing the updated text? Make sure that npm start is running continuously, and that it's not reporting any errors. Also make sure that "Hello World → Use Local Resources" is checked.
Understand Your App
Let's take a closer look at the code of your first app. The source code lives in the src/
directory, containing these three files:
// root.jsx
import quip from "quip";
import App from "./App.jsx";
quip.apps.initialize({
initializationCallback: function(rootNode) {
ReactDOM.render(<App/>, rootNode);
},
});
// App.jsx
import Styles from "./App.less";
export default class App extends React.Component {
render() {
return <div className={Styles.hello}>YES it worked!</div>;
}
}
// App.less
.hello {
display: flex;
justify-content: center;
}
What's going on
quip.apps.initialize()
is the starting point. By calling it, your app notifies the Quip document that its code has loaded and it is ready for setup.- The Quip document then calls back into your app via
initializationCallback
to notify that setup is complete and all data for your app instance is ready. - Your app lives in an iframe — inside there,
rootNode
is the empty HTML element where your app must live. Your code can add anything to this HTML element, with or without React. - This code uses React to render
into the HTML element.<App/>
Styles.hello
refers to the.hello
class name imported fromApp.less
.- As you develop your app, you'll add new
.jsx
and.less
files to thesrc/
directory (or subdirectories).