Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rewrite getting started guide #1766

Merged
merged 9 commits into from
Jan 18, 2021
Merged

Rewrite getting started guide #1766

Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4fbe614
redo getting started guide
alexandra-simeonova Dec 9, 2020
f6b969c
format changes
alexandra-simeonova Dec 9, 2020
50e9ae1
Merge branch 'master' into improve-getting-started
UlianaMunich Dec 10, 2020
da92786
Merge branch 'master' into improve-getting-started
UlianaMunich Dec 11, 2020
50477b8
Apply suggestions from code review
alexandra-simeonova Dec 11, 2020
ccafc3c
Merge branch 'master' into improve-getting-started
alexandra-simeonova Dec 14, 2020
bdd22b2
Merge branch 'master' into improve-getting-started
legteodav Dec 15, 2020
cc26a18
Merge branch 'master' into improve-getting-started
hardl Jan 4, 2021
51ca635
Merge branch 'master' into improve-getting-started
alexandra-simeonova Jan 18, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 76 additions & 39 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,23 +17,68 @@ meta -->

## Overview

Luigi is an open source JavaScript framework for micro frontends. It enables you to:
* create a unified user interface for a web application using **Luigi Core**.
* create micro frontends and connect them to the Luigi Core app using **Luigi Client**.
Luigi is an open source JavaScript framework for **micro frontends**. Micro frontends can be used to divide big frontend monoliths into smaller, simpler, independent chunks.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Luigi is an open source JavaScript framework for **micro frontends**. Micro frontends can be used to divide big frontend monoliths into smaller, simpler, independent chunks.
Luigi is an open source JavaScript framework for **micro frontends**. Micro frontends that can be used to divide big frontend monoliths into smaller, simpler, independent chunks.


This diagram illustrates the structure of Luigi:
<!-- add-attribute:class:success -->
>**TIP:** Go to our [FAQ section](faq.md) to find more detailed answers to questions like *What are micro frontends?*

The Luigi framework provides configuration options, API functions, and out-of-the-box features which make migrating to a micro frontend architecture easier.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The Luigi framework provides configuration options, API functions, and out-of-the-box features which make migrating to a micro frontend architecture easier.
The Luigi framework provides configuration options, API functions and out-of-the-box features which make migrating to a micro frontend architecture easier.


Furthermore, Luigi is **technology-agnostic**, which means you can use toolkits like OpenUI5, Angular, React, Vue, or anything else to create your frontend.

### Main features

<img src="https://github.com/SAP/luigi/blob/master/docs/assets/luigi-overview-diagram.jpg?raw=true" width="600"/>

Do you want to try out Luigi without installing it on your machine? Try one of these options:
Luigi consists of two main parts:

**Luigi Core** - refers to the "main app", in which your micro frontends (a.k.a. views) will be embedded. It offers some of the following configurable features:
* [Navigation](navigation-configuration.md) - consistent user navigation created using specific Luigi [parameters](navigation-parameters-reference.md).
* [Authorization](authorization-configuration.md) - integration with an authentication provider, allowing users to log in.
* [Localization](i18n.md) - displaying an application in multiple languages.
* [General settings](general-settings.md) - other settings that can be configured in Luigi, such as HTML attributes, third-party cookie configuration and more.
* [API](luigi-core-api.md) - functions to help with almost every part of your app: navigation, authorization, adding a [search box](luigi-core-api.md#globalsearch), configuring a light/dark [theme](luigi-core-api.md#theming) and others.

**Luigi Client** - refers to Luigi options related to micro frontends:
* [API](luigi-client-api.md) - diverse API functions which can be used on the micro frontend side.
* [Communication](communication.md) - sending messages between the micro frontend and the main application (Luigi Core module).

## Setup

If you want to begin developing your own app with Luigi, start here:

### Luigi Core

Follow these steps to create a global user interface and host a **full web application** in Luigi:

1. Set up a Luigi Core application on one of the following frameworks:
* [No framework](application-setup.md#application-setup-without-a-framework)
* [Angular](application-setup.md#application-setup-for-angular)
* [SAPUI5/OpenUI5](application-setup.md#application-setup-for-sapui5openui5)
* [VUE.JS](application-setup.md#application-setup-for-vuejs)
* [React](application-setup.md#application-setup-for-react)

2. Configure the application according to your needs. For example, you can begin by configuring the [basic navigation](navigation-configuration.md) of your application.

### Luigi Client

Follow these steps to add Luigi Client features to your existing **micro frontends**:

1. [Install Luigi Client](luigi-client-setup.md).
2. Use the functions and parameters provided by the Luigi Client API. You can find them in the [Luigi Client API documentation](luigi-client-api.md).


## Examples

Here you can find some Luigi example applications and scenarios, starting from simple to more complex:

<!-- accordion:start -->

### HTML file

It is possible to create a Luigi application using a single HTML file. This example aims to show the simplicity of Luigi, but it is not intended for real-life use.
This is a *very simple* example of a Luigi application inside a single HTML file. It is not intended for any real-life use.

Copy and paste this code in a text editor, then save it as an HTML file:
You can run it by copying and pasting this code in a text editor, then saving it as an HTML file:

```html
<!DOCTYPE html>
Expand Down Expand Up @@ -99,38 +144,10 @@ Copy and paste this code in a text editor, then save it as an HTML file:
```

### Luigi Fiddle
Go to the [Luigi Fiddle](https://fiddle.luigi-project.io/) website. Click on **Modify Config** at the bottom right of the page to make changes to the Luigi application.

<!-- accordion:end -->

## Prerequisites
The [Luigi Fiddle](https://fiddle.luigi-project.io/) website is a sandbox playground where you can test Luigi. Simply click on **Modify Config** at the bottom right of the page to make changes to the Luigi application.

* Basic knowledge of HTML
* Basic knowledge of JavaScript

## Setup

### Luigi Core

Follow these steps to create a global user interface and host a **full web application** in Luigi:

1. Set up a Luigi Core application on one of the following frameworks:
* [No framework](application-setup.md#application-setup-without-a-framework)
* [Angular](application-setup.md#application-setup-for-angular)
* [SAPUI5/OpenUI5](application-setup.md#application-setup-for-sapui5openui5)
* [VUE.JS](application-setup.md#application-setup-for-vuejs)
* [React](application-setup.md#application-setup-for-react)

2. Configure the application according to your needs. For example, you can begin by configuring the [basic navigation](navigation-configuration.md) of your application.

### Luigi Client

Follow these steps to develop **micro frontends** and connect them to an already existing Luigi Core app:

1. [Install Luigi Client](luigi-client-setup.md).
2. Use the functions and parameters provided by the Luigi Client API. You can find them in the [Luigi Client API documentation](luigi-client-api.md).

### Examples
### "Hello World" examples

In the **Examples** section of our documentation, you can find links to several "Hello World" example applications which can help you explore Luigi's functions:
* [Angular](https://github.com/SAP/luigi/tree/master/core/examples/luigi-example-angular)
Expand All @@ -139,8 +156,28 @@ In the **Examples** section of our documentation, you can find links to several
* [OpenUI5](https://github.com/SAP/luigi/tree/master/core/examples/luigi-example-openui5)
* [Svelte](https://github.com/SAP/luigi/tree/master/core/examples/luigi-example-svelte)
* [Plain JavaScript](https://github.com/SAP/luigi/tree/master/core/examples/luigi-example-js)
* [NextJS](https://github.com/SAP/luigi/tree/master/core/examples/luigi-example-next)

You can install them by following the instructions in the `README` file of each example.

**Advanced users** can install our end-to-end test sample application which includes all of Luigi's features in one place:
* [e2e example](https://github.com/SAP/luigi/tree/master/test/e2e-test-application)
### Luigi shopping app (tutorial)

Our [tutorial](https://developers.sap.com/group.luigi-app.html) on how to create a React and UI5 web-shopping application is intended for beginners, but it still delves deeper into Luigi's functions. It covers topics such as:
- how to create a Luigi app from scratch
- how to use the Luigi Core and Client APIs
- how to create a micro frontend
- how to add localization to your app and display it in multiple languages

The whole tutorial should take about an hour to complete. The source code for the tutorial app can be found [here](https://github.com/SAP-samples/luigi-micro-frontend-application).

### e2e example

This example application was created for testing purposes and it includes all possible Luigi features in one place. It might be complicated and unsuitable for beginners, but useful if you want to explore our framework in more detail or [contribute](https://github.com/SAP/luigi/blob/master/CONTRIBUTING.md) to the Luigi project.

You can find the e2e test application and instructions on how to install it [here](https://github.com/SAP/luigi/tree/master/test/e2e-test-application#luigi-sample-and-e2e-test-application-written-in-angular).

### Advanced scenarios

In the [expert scenarios](advanced-scenarios.md) section of the documentatation, you can find implementations of more complex Luigi use cases, such as using feature toggles or authenticating with Google Cloud Identity.

<!-- accordion:end -->