CLI

Beagle Backend TypeScript CLI

This is the CLI for Beagle Backend TypeScript, where you can quickly create a new project and generate screens.

Getting Started

In this section you will learn how to quickly set up a project and start using the Beagle Backend TypeScript!

Setting Up a Project

Install the Beagle Backend TypeScript CLI globally:

npm install -g @zup-it/beagle-backend-typescript-cli

Create a new project:

beagle-ts new [PROJECT NAME]

Run the application:

cd [PROJECT NAME]
npm run start

Generating a Basic Screen

Go to the project root and run:

beagle-ts generate-screen [SCREEN NAME]

The new screen will be generated inside the folder: src/screens, or inside the folder defined on the attribute screensFolderPath in the configuration file ./beagle-ts.json.

The generated screen code will be:

/** ./src/screens/screen-name.tsx */

import { BeagleJSX } from '@zup-it/beagle-backend-core'
import { Text } from '@zup-it/beagle-backend-components'

export const ScreenNameScreen = () => (
  <>
    <Text>This the ScreenNameScreen screen component!</Text>
  </>
)

Routing

Also, when you generate a screen, your new screen is added to the app RouteMap, like this:

/** ./src/screens/index.tsx */

import { RouteMap } from '@zup-it/beagle-backend-express'
import { Home } from './home'
import { Welcome } from './welcome'
import { ScreenName } from './screen-name'

export const routes: RouteMap = {
  '': Welcome,
  '/home': Home,
  '/screen-name': ScreenName,
}

CLI Commands and Options

In this section you will find all the options that the CLI has to offer.

Command: beagle-ts new [PROJECT NAME]

Creates a new Beagle Backend TypeScript project with a boilerplate structure.

Arguments:

Argument	Description
[project-name]	Name of the project. eg. "name-of-my-project" (will be the name of the folder).

Options:

Option	Alias	Description	Default Value
--base-path	-bp	Base path that will be the root of the API.	''
--port	-p	Port where the service will run.	3000

Command: beagle-ts generate-screen [SCREEN NAME] or beagle-ts gs [SCREEN NAME]

Creates a new Beagle Backend TypeScript project with a boilerplate structure.

Arguments:

Argument	Description
[screen-name]	Name of the screen that will be generated. eg. "name-of-my-screen".

Options (all options are boolean):

Option	Alias	Description	Default Value
--with-route-params	-wrp	The screen will have parameters on the url.	false
--with-headers	-wh	The screen will have headers to be sent in the request.	false
--with-body	-wb	The screen will have a request body. Invalid for "GET" requests.	false
--with-query	-wq	The screen will have properties in the urls query.	false
--with-navigation-context	-wnc	The screen will have properties to be set in the navigation context.	false
--with-context	-wctx	A Context that will be made available for this Screen and its children.	false
--with-children	-wc	The children of this Screen.	false
--with-accessibility	-wac	The Screen will support accessibility properties.	false
--with-analytics	-way	The Screen will support analytics.	false
--with-style	-ws	The style for this Screen. Use it to customize the background, layout, borders, etc.	false

The options on the generation of a screen are for the properties of that screen component, like when you need some features for it.

Sample of Screen Generation with Options

If you are on a scenario which requires that your screen must have a NavigationContext to be accessed and also that screen will have child components, you can simply run:

beagle-ts generate-screen --with-navigation-context --with-children screen-name 

or through alias:

beagle-ts gs -wnc -wc screen-name 

The new screen will be generated with your desired attributes already set, so you can start a new screen faster. The screen generated will be like this:

/** ./src/screens/screen-name.tsx */

import { BeagleJSX, WithChildren } from '@zup-it/beagle-backend-core'
import { Text } from '@zup-it/beagle-backend-components'
import { Screen } from '@zup-it/beagle-backend-express'

interface ScreenNameProps extends WithChildren {
  "navigationContext": {
    "your": "navigationContext"
  }
}

export const ScreenName: Screen<ScreenNameProps> = () => (
  <>
    <Text>This the ScreenName screen component!</Text>
  </>
)

Configuration file (./beagle-ts.json)

When you create a new project through the CLI, beside the whole boilerplate structure, a new configuration file will be created on the root of the new project, named: beagle-ts.json. This configuration file will have some attributes required by the CLI to generate screens and also start the express server.

Note: If you want to handle the express attributes with your own strategy, you don't need the configuration file on your application, but you MUST HAVE it if you want to use the generate screen command.

The configuration file has this attributes:

/** ./beagle-ts.json */

{
  /** The name of your project. */
  "projectName": "first-one",

  /** The port where the express app will be running. 
   @defaultValue 3000 
  */
  "port": "3000",

  /** The base path of your exposed service. eg: if is set as "api", your service will be like this: "https://localhost:3000/api/[your-route]".
   @defaultValue "" (empty string)
  */
  "basePath": "",

  /** The path to your screens files folder.
   @defaultValue 'src/screens' 
  */
  "screensFolderPath": "src/screens",

  /** Configuartions for routing. */
  "routes": {

    /** Path to the file where the routes are defined.
     @defaultValue 'src/screens/index.ts'
    */
    "filePath": "src/screens/index.ts",

    /** The name of the variable where the routes are defined inside the file defined on the `filePath` property.
     @defaultValue 'routes'
    */
    "varName": "routes"
  }
}

Files Generated by the CLI (Boilerplate)

When you generate a project using the CLI, a boilerplate project will be created with the name that you defined. For example, if you run beagle-ts new project-name, the structure generated will be:

📦 project-name
 ┣ 📂 src
 ┃ ┣ 📂 screens
 ┃ ┃ ┣ 📜 home.tsx  // example of navigation between screens
 ┃ ┃ ┣ 📜 index.ts  // file where the routes are defined
 ┃ ┃ ┗ 📜 welcome.tsx  // example for default page
 ┃ ┣ 📜 config.ts  // file that have methods to get the BeagleTsConfig
 ┃ ┣ 📜 global-context.ts  // declaration of GlobalContext and example for its usage
 ┃ ┗ 📜 index.ts  // root of the express app, where everything is set up
 ┣ 📜 .editorconfig
 ┣ 📜 .eslintrc.js
 ┣ 📜 LICENSE
 ┣ 📜 README.md
 ┣ 📜 beagle-ts.json  // configuration file to be used by the CLI and the Express App  
 ┣ 📜 package-lock.json
 ┣ 📜 package.json
 ┗ 📜 tsconfig.json