# @canonic/cli

> CLI for Canonic

Latest version **1.0.1** (published 2021-06-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @canonic/cli
pnpm add @canonic/cli
yarn add @canonic/cli
bun add @canonic/cli
```

Provides the commands `cnc`, `canonic`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2021-06-30 |
| First published | 2021-05-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 28 |
| Unpacked size | 282.7 KB |
| Known vulnerabilities | 0 (+6 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | pratham.agrawal92 |

## Links

- npm: https://www.npmjs.com/package/@canonic/cli
- npm.io page: https://npm.io/package/@canonic/cli

## Dependencies (28)

- [ink](https://npm.io/package/ink.md) ^3.0.8
- [chalk](https://npm.io/package/chalk.md) ^4.1.1
- [gotql](https://npm.io/package/gotql.md) ^2.0.5
- [react](https://npm.io/package/react.md) ^17.0.2
- [yargs](https://npm.io/package/yargs.md) ^17.0.1
- [fuse.js](https://npm.io/package/fuse.js.md) ^6.4.6
- [webpack](https://npm.io/package/webpack.md) ^5.36.2
- [chromafi](https://npm.io/package/chromafi.md) ^2.1.0
- [fs-extra](https://npm.io/package/fs-extra.md) ^9.1.0
- [ink-link](https://npm.io/package/ink-link.md) ^2.0.0
- [prettier](https://npm.io/package/prettier.md) ^2.2.1
- [handlebars](https://npm.io/package/handlebars.md) ^4.7.7
- [node-fetch](https://npm.io/package/node-fetch.md) ^2.6.1
- [change-case](https://npm.io/package/change-case.md) ^4.1.2
- [ink-divider](https://npm.io/package/ink-divider.md) ^3.0.0
- [ink-spinner](https://npm.io/package/ink-spinner.md) ^4.0.1
- [highlight.js](https://npm.io/package/highlight.js.md) ^10.7.2
- [ink-big-text](https://npm.io/package/ink-big-text.md) ^1.2.0
- [cli-highlight](https://npm.io/package/cli-highlight.md) ^2.1.11
- [ink-text-input](https://npm.io/package/ink-text-input.md) ^4.0.1
- [ink-quicksearch](https://npm.io/package/ink-quicksearch.md) ^0.3.2
- [@12core/chromafi](https://npm.io/package/@12core/chromafi.md) ^3.0.3
- [ink-select-input](https://npm.io/package/ink-select-input.md) ^4.2.0
- [ink-confirm-input](https://npm.io/package/ink-confirm-input.md) ^2.0.0
- [webpack-dev-server](https://npm.io/package/webpack-dev-server.md) ^3.11.2
- [ink-syntax-highlight](https://npm.io/package/ink-syntax-highlight.md) ^1.0.1
- [ink-quicksearch-input](https://npm.io/package/ink-quicksearch-input.md) ^1.0.0
- [@trufflesuite/chromafi](https://npm.io/package/@trufflesuite/chromafi.md) ^2.2.2

## Recent versions

- 1.0.1 (latest) — 2021-06-30
- 1.0.1-develop.1 (beta) — 2021-06-30
- 1.0.0 — 2021-06-29
- 1.0.3 — 2021-05-14
- 1.0.0-develop.1 — 2021-05-14

## README

<!-- omit in toc -->
# Canonic CLI
// badges

[Logo]
[Screenshot]

Subtitle

<br/>

<!-- omit in toc -->
## Table of Contents
- [Introduction](#introduction)
- [How to use](#how-to-use)
  - [Installation](#installation)
  - [Authentication](#authentication)
- [Commands](#commands)
  - [`cnc init <PROJECT_NAME>`](#cnc-init-project_name)
  - [`cnc start`](#cnc-start)
  - [`cnc generate`](#cnc-generate)
  - [`cnc deploy`](#cnc-deploy)
- [Client SDK Reference](#client-sdk-reference)
    - [Importing the SDK](#importing-the-sdk)
    - [Queries](#queries)
    - [Mutations](#mutations)
- [Recipes](#recipes)
  - [`canonic.config.json`](#canonicconfigjson)
  - [The `--ci` argument](#the---ci-argument)
  - [Syncing an existing project](#syncing-an-existing-project)
- [Troubleshooting](#troubleshooting)
  - [`Invalid Auth Token`](#invalid-auth-token)
  - [`Canonic.config.json not found`](#canonicconfigjson-not-found)
- [Templates](#templates)
  - [`react-app`](#react-app)
  - [`angular-app`](#angular-app)
  - [`gatsby-app`](#gatsby-app)
  - [`nextjs-app`](#nextjs-app)
- [Further Reading](#further-reading)

<br/>

## 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.

<br/>

## 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]

<br/>

## 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. 

<!-- omit in toc -->
#### Example: 

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

Change your directory to the newly created application
```bash
cd my-app
```
Start the development server to start coding!
```bash
cnc start
```
The development server should be up and running on http://localhost:8000

<br/>

### `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.**

<br/>

### `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.
  
    ```jsx
    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!)
  
    ```jsx
    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`

<br/>

### `cnc deploy`
> Deploys your frontend app to a CDN powered by Canonic.

[Screenshot]

**Coming Soon!**

<br/>

## 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
```jsx
import MySDK from "@canonic/my"
```
> All your endpoints are namespaced by the tables under which they are created.

#### Queries
> For `GET` API Calls

```js
/***
 * 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:
> ```jsx
> 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

```js
/***
 * 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:
> ```jsx
> 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}>...
> }
> ```

<br/>

## 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.

```json
{
  "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`

<br/>

## 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.

<br/>

## 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!**

<br/>

## Further Reading

- Canonic Documentation
- Canonic Samples 
- Discord Community

---
_Source: https://npm.io/package/@canonic/cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
