Quick start tutorial

This tutorial will get you started with a ready-to-go development environment based on Node.js, TypeScript, and Parcel.js.

Prerequisites

If you don't already have Node.js installed on your computer, install it now.

If you don't have a code editor or IDE installed on your computer, you can install VS Code. This is optional. You can use any plain text editor or code editor if you prefer.

Setting up the project

Create a directory to store your project. Then open a shell window (bash, PowerShell, cmd, etc.) and change to your project directory with a command like:

cd path/to/my/project

We will use a tool called npm to install some files in this directory (npm is part of Node.js). First we need to set things up for npm by telling it that we want to start a new project in this directory:

npm init -y

This will create a default package.json file that describes your project and its dependencies. Now we can install the package that will give us access to the Math I Can Do API:

npm install https://www.mathicando.com/api/micd/mathicando-api.tgz

Tip: Once installed, you can update the module by running npm update mathicando-api. This will ensure your IDE and build tools have type information for the latest API updates.

And finally, install Parcel.js, which will take care of the boring details of building your app:

npm install --save-dev parcel-bundler

The --save-dev signifies that Parcel.js will be used to help develop the project, but that it isn't part of the finished product.

Writing the app

Now we are ready to start writing the app. We'll need a basic HTML file to serve as the app's entry point. If you are using VS Code, you should start it now and choose the File > Open Folder menu item, then choose your project folder. You can use it to create and edit these files. Otherwise, use whatever text editor you have chosen. Here's the file you need to create:

index.html

<!DOCTYPE html>
<html>
<head>
    <title>Quick start app</title>
</head>
<body>
  <script src="./main.ts"></script>
</body>
</html>

Notice the reference to the main.ts script. The .ts extension indicates that the code for the script will be written in TypeScript, a popular language that is a superset of JavaScript. Using TypeScript lets us make better use of the type information available for the API. The sample code playground also uses TypeScript, so you can easily borrow from those examples when writing your app. (Web browsers can't handle TypeScript code directly, but that will be taken care of automatically by Parcel.js.) Create main.ts now:

main.ts

import { createApi } from "mathicando-api";

const API_KEY = "000-0000-0000-0000-0000-000";

createApi(API_KEY).then(async micd => {
    // you can freely use the Math I Can Do API here
    const shell = await micd.shell.create(document.body);
    shell.view.type("`Hey there!`");
    shell.focus();
});

We are almost ready to try the app, but first we need to modify the package.json file to set up Parcel.js. Find the "scripts": section of package.json and edit it as follows:

package.json

{
    ...other stuff...

    "scripts": {
        "dev": "parcel index.html",
        "build": "parcel build index.html --public-url ./"
    },

    ...other stuff...
}

Testing it out

If you are using VS Code, you may want to open one of its built-in terminal windows (Terminal > New Terminal). Or, switch back to the terminal window you were using before. In either case, from your project directory run the following command:

npm run dev

This will have to do some work, especially the first time you run it. Wait for it to finish, and look for a line like the following:

Server running at http://localhost:1234

The "1234" might be different. Select and copy the URL, and paste it into a new browser tab. In a moment, you should see a Math I Can Do editor shell with the message "Hey there!".

If this step fails, check that the contents of your files match the instructions above. If that's not the problem, it might be an issue with Parcel.js. Try switching to a specific version known to work: press Ctrl+C in the terminal window to stop Parcel.js if it is running, then run npm install --save-dev parcel-bundler@1.12.3. Finally, try running npm run dev again.

Making changes

Because you are running in development (dev) mode, changes to the source files should show up automatically in the browser tab. In main.ts, try adding an extra ! to Hey there! and save the file. In a moment the page should reload with the modified message.

At this point, if you start opening and closing some of the shell's command palettes you will see that the shell freely grows and shrinks. This is because the <body> element it was added to grows to whatever height is needed by its children. Let's add a stylesheet to the page to fix that.

Create a new file named index.css in the project directory, but don't add anything to it yet. Go back to index.html and edit the <head> as follows:

index.html

<head>
    <title>Quick start app</title>
    <link rel="stylesheet" href="./index.css">
</head>

Save those changes and the page will reload. Now edit index.css:

index.css

html, body {
    margin: 0;
    width: 100%;
    height: 100%;
    overflow: hidden;
}

Saving index.css won't reload the whole page. It will just swap in the new stylesheet.

You are ready to start building your app. Check out the playground or full API for ideas on what to try next. Have fun!

Deploying your app

To build a production version of your app, you would run the build script instead of the dev script. If you were still running in dev mode, you'd stop that first by pressing Ctrl+C in the terminal window. Then you'd run:

npm run build

Parcel.js would then build the production version of your app, placing the resulting files in the dist subdirectory of your project. To deploy your app, you'd upload the contents of dist to your hosting service.

Important: Deployed apps will not work unless you replace the API_KEY value in main.ts with a valid key. Contact us to get an API key.

Back to contents