Setting your workspace

This guide explains how to set up your environment using the ragu-cli tool. It includes installing the CLI, creating an initial workspace and simple micro-frontend. Also, this guide explains how to run the micro-frontend locally.

Start a Node project#

I already have a node project
Tell me how to start one

If you don't have a project yet 1 open your terminal and follow the steps bellow:

2 Create a directory.

mkdir my-mfe

3 Open the directory you have created.

cd my-mfe

4 Create a node project

Yarn
NPM

yarn init

Install the ragu-cli#

You use the ragu-cli to build micro-frontends, develop and preview your micro-frontend.

To install the ragu-cli, execute the following command at the terminal:

Yarn
NPM

yarn add ragu-cli --dev

Webpack#

Ragu abstracts part of webpack configuration. It means that you should not worry about having a webpack config file if you don't use any special loader. However, webpack must be installed manually to make sure Ragu is using the same webpack version of your project. You can skip this step if you already have webpack installed.

Yarn
NPM

yarn add webpack --dev

Adapters#

Ragu is technology-agnostic. That means it can be used with any javascript framework. However, ragu-cli needs to know how to build your project. The adapters are how you can tell Ragu how to build the micro-frontend. For this example we will use the adapter for vanilla (a.k.a pure javascript) micro-frontends.

Yarn
NPM

yarn add ragu-simple-adapter --dev

note

All the examples bellow are about exporting a javascript pure micro-frontend. There is even a smooth way to work with your favorite framework. Check React's and Vue's documentation for more info.

info

Does not install the simple adapter if you will use a framework. Install the framework adapter instead.

Creating a simple component#

Open your favorite text editor and create a javascript file for out micro-frontend:

my-mfe.js

export default () => {
  return {
    html: 'Hello, World'
  }
}

note

A Ragu micro-frontend is always a file that exports a default function.

Run the application#

The Ragu includes a server, so that you can build and serve your app locally.

Run the following command to start the development server:

Yarn
NPM

yarn ragu-cli dev --file my-mfe.js

The output should be like this:

📦 your build is ready!

Output path: .ragu-components
Base URL: http://localhost:3100

🗺 Component Routes:
▸ mfe: http://localhost:3100/

🔭 Preview Routes:
▸ mfe: http://localhost:3100/preview

Welcome to 🔪 Ragu

Now you can use your micro-frontend wherever you want even here!

Your local micro-frontend

info

Try to change the micro-frontend! You will see that changes will be reflected here!

Code Example

The code of the examples above can be found here.

Previewing your micro-frontend#

To preview your micro-frontend you just need to open the preview route that is printed at the terminal when you start the development server. Preview has hot-reload - changes are automatically updated.

The default micro-frontend route is http://localhost:3100/preview

Check all available commands and options#

If you are having troubles to remember any ragu-cli commands or options you can use the --help flag.

Yarn
NPM

yarn ragu-cli --help

Usage: ragu-cli [options] [command]

Welcome to ragu-cli. Check the list of commands bellow:

Options:
  -V, --version     output the version number
  -h, --help        display help for command

Commands:
  dev [options]     Starts ragu server in development mode for the given component.
  static [options]  Build the project as a static ragu project
  build [options]   Build the project to production
  serve [options]   Production server. You must the same options given for build command.
  help [command]    display help for command

You can combine a command with the --help flag to list all available options for that command. Example:

Yarn
NPM

yarn ragu-cli dev --help

Usage: ragu-cli dev [options]

Starts ragu server in development mode for the given component.

Options:
  --ssrEnabled                             Enables SSR
  --file <file>                            Your component file
  --stateFile <stateFile>                  Your component file
  --dependencies <dependencies>            Project external dependencies
  --directory <directory>                  The directory for multiple components server
  --log <log>                              The application log level: debug, info, warn, error
  --adapter <adapter>                      The adapter for your component: react, vue, custom
  --baseurl <baseurl>                      Your component baseurl where you component will be deployed
  --configFile <configFile>                A custom config file
  --port <port>                            The server port
  --outputPath <outputPath>                Where your component will be built. Default: .ragu-components
  --webpack <webpack>                      A custom webpack config
  --webpackServerSide <webpackServerSide>  A custom webpack config for SSR. Default: It will assume the same value provided for --webpack
  -h, --help                               display help for command