@canonic/cli v1.0.1

Canonic CLI

// badges

Logo

Subtitle

Table of Contents

• Introduction
• How to use
  • Installation
  • Authentication
• Commands
  • cnc init <PROJECT_NAME>
  • cnc start
  • cnc generate
  • cnc deploy
• Client SDK Reference
  • Importing the SDK
  • Queries
  • Mutations
• Recipes
  • canonic.config.json
  • The --ci argument
  • Syncing an existing project
• Troubleshooting
  • Invalid Auth Token
  • Canonic.config.json not found
• Templates
  • react-app
  • angular-app
  • gatsby-app
  • nextjs-app
• Further Reading

Introduction

Canonic's CLI enables you to integrate Canonic and it's APIs into your frontend application swiftly and in just a few steps.

If you're just starting out with the frontend, it can also bootstrap the app with Canonic fully integrated and ready to deploy.

It also generates a customized SDK for you canonic project that completely eliminates the networking layer allowing to interact with those APIs without much effort.

How to use

The cli can be installed through npm globally or can be used in conjunction with npx.

Installation

 yarn add -G @canonic/cli

Authentication

The SDK requires a personal access token to authenticate your actions with Canonic and associate them with your account.

You can generate a personal access token by logging in and going to your profile -> Access Tokens.

Screenshot

Commands

cnc init <PROJECT_NAME>

Initialises and bootstraps a new or existing project.

Screenshot

When starting a project from scratch, the command generates a new project on Canonic. It also bootstraps a new frontend application based on the template specified.

To generate a new project, run cnc init PROJECT_NAME where PROJECT_NAME is the name of the folder where the application will be created. You will be guided through an interactive cli to create the new project.

If you already have an existing project on Canonic, it can automatically generate and link it with the new app that's being initialized.

Example:

Bootstrap a frontend project inside the my-app directory. Make sure it doesn't exist before running this command.

cnc init my-app

Change your directory to the newly created application

cd my-app

Start the development server to start coding!

cnc start

The development server should be up and running on http://localhost:8000

cnc start

Start the dev server and refresh your application automatically as it changes.

Screenshot

When developing frontend applications, it's usually desirable to have a development server running that automatically refreshes the application when changes to the code are made. You can start the development server by running cnc start inside your canonic frontend application. The CLI looks for the canonic.config.js file created next to package.json.

In case authentication credentials are not found on the system, the user is prompted to enter their Personal Access Token

The development server runs on port 8000 by default.

It also syncs the custom Canonic SDK. Any endpoints edited/added/deleted are refreshed and can be used immediately post deploy.

cnc generate

Generates a dynamic SDK to interact with your project's various endpoints.

Screenshot

It's often tricky and repetitive to setup the networking layer for your frontend application. With cnc generate you can generate a custom client SDK for your Canonic project.

It comes with code completion! Autocomplete makes it a breeze to call and interact with all your Canonic endpoints.

The SDK can be consumed on 2 different levels of complexity:

• React + Apollo GraphQL Hooks: Comes in-built with caching and other performance optimisations. All your endpoints are available as simple to use React hooks.

  import MyAppSDK from '@canonic/my'
  
  export default function MyApp() {
    const { data: movies = [], loading } = MyAppSDK.movies.useMovies();
    return movies.map(...
  }

• Javascript SDK based on fetch: This is a lower level abstraction that exposes your Canonic project's various endpoints as simple to call functions. (They return promises!)

  import MyAppSDK from '@canonic/my/core'
  
  export default function MyApp() {
    return MyAppSDK.movies
      .getMovies()
      .then(movies => console.log('MOVIES', movies));
  }

For React projects, we recommend using the hooks as it comes in built with caching that can dramatically increase the performance of GET based APIs. Best used in conjunction with @canonic/sdk

cnc deploy

Deploys your frontend app to a CDN powered by Canonic.

Screenshot

Coming Soon!

Client SDK Reference

cnc generate generates a custom SDK just for your Canonic project.

React Hooks are the default import for @canonic/my. This package is generated whenever you run cnc init. It is refreshed whenever changes are made to your Canonic project.

For exact documentation pertaining to your specific project, you can open your project on Canonic and head over to the docs tab for examples on how to call your endpoints.

Importing the SDK

import MySDK from "@canonic/my"

All your endpoints are namespaced by the tables under which they are created.

Queries

For GET API Calls

/***
 * Call the relevant endpoint
 * @param   {String}  TABLE_KEY       The key for the table
 * @param   {String}  ENDPOINT_KEY    The key for the endpoint (first letter capitalized)
 * @param   {Object}  input           The input object as defined in the endpoint
 * 
 * @return  {Object}  params          An object containing data, loading, error
 * @return  {Object}  params.data     The object that's defined as the output of the endpoint
 * @return  {Bool}    params.loading  Is true when the api is actively fetching data
 * @return  {Object}  params.error    In case the api call fails, this object contains it's data
 * */
MySDK.TABLE_KEY.useENDPOINT_KEY(input)

Example:

import MySDK from "@canonic/my";

function MyContainer(props) {
  const { data, loading, error } = MySDK.movies.useMovie({
    _id: "test-id",
  });
  
  return <div>...
}

Mutations

For POST/PUT/PATCH/DELETE API Calls

/***
 * Call the relevant endpoint
 * @param {String}    TABLE_KEY       The key for the table
 * @param {String}    ENDPOINT_KEY    The key for the endpoint (first letter capitalized)
 * @param {Object}    input           The input object as defined in the endpoint
 * 
 * @return {Object}   params          An object containing data, loading, error
 * @return {Function} params.trigger  Triggers the mutation / endpoint.
 * @return {Object}   params.data     The object that's defined as the output of the endpoint
 * @return {Bool}     params.loading  Is true when the api is actively fetching data
 * @return {Object}   params.error    In case the api call fails, this object contains it's data
 * */
MySDK.TABLE_KEY.useENDPOINT_KEY(input)

Example:

import MySDK from "@canonic/my";

function MyContainer(props) {
  const { createMovie, data, loading, error } = MySDK.movies.useCreateMovie();
  
  const handleClick = React.useCallback(() => {
     createMovie({ title: 'Yes We Can' });
  }, [createMovie])
  
  return <div onClick={handleClick}>...
}

Recipes

canonic.config.json

Information about which Canonic project and other relevant settings are stored in the canonic.config.js file usually located right next to your package.json. This file is automatically generated when cnc init or cnc generate is called.

{
  "title" : "SDK Project",
  "key"   : "sdkProject-i973j4"
}

The --ci argument

You can pass --ci to any of the above commands, and it would use the non-interactive scripts instead. This is particularly useful when automating deployments through a CI provider.

Syncing an existing project

You can sync existing projects by running the cnc generate command. It will guide you through project selection and integration. Once complete, you can simply import the custom sdk from @canonic/my

Troubleshooting

Invalid Auth Token

Your authentication token might be corrupted or might have been revoked. You can generate a new access token in your user settings on Canonic. File an issue if you feel that a valid token is no longer working.

Canonic.config.json not found

canonic.config.json is used by the CLI to reliably link your Canonic backend with your frontend. You can either run cnc generate to automatically create the file, or generate it manually.

Templates

react-app

create-react-app inspired starter. It helps get started with building a React app linked with Canonic. It comes with @canonic/sdk integrated, giving you access to powerful frontend components that handle the networking layer making frontend development significantly faster.

angular-app

Coming Soon!

gatsby-app

Coming Soon!

nextjs-app

Coming Soon!

Further Reading

• Canonic Documentation
• Canonic Samples
• Discord Community