@canonic/cli v1.0.1
Canonic CLI
// badges
Subtitle
Table of Contents
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.
Commands
cnc init <PROJECT_NAME>
Initialises and bootstraps a new or existing project.
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.
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.
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.
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 runcnc 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
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago