Skip to content

Commit

Permalink
docs: Improvements after Alex Martel review (#75)
Browse files Browse the repository at this point in the history 
* Docs improvements

* More docs

* More docs

* More docs

* More docs

* More docs
  • Loading branch information
@patricklafrance
patricklafrance authored Sep 14, 2023
1 parent ccff1eb commit a4d4a37
Show file tree
Hide file tree
Showing 8 changed files with 462 additions and 115 deletions.
81 changes: 62 additions & 19 deletions docs/getting-started/create-host.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,29 +5,34 @@ label: Create an host app

# Create an host application


Let's begin by creating the application that will serve as the entry point for our federated application and host the application modules.

## 1. Install the packages

Create a new project (we'll refer to ours as `host`), then open a terminal at the root of the new solution and install the following packages:
Create a new application (we'll refer to ours as `host`), then open a terminal at the root of the new solution and install the following packages:

+++ pnpm
```bash
pnpm add -D @workleap/webpack-configs @workleap/swc-configs webpack webpack-dev-server webpack-cli @swc/core @swc/helpers browserslist postcss
pnpm add -D @workleap/webpack-configs @workleap/swc-configs @workleap/browserslist-config webpack webpack-dev-server webpack-cli @swc/core @swc/helpers browserslist postcss typescript
pnpm add @squide/core @squide/react-router @squide/webpack-module-federation react react-dom react-router-dom
```
+++ yarn
```bash
yarn add -D @workleap/webpack-configs @workleap/swc-configs webpack webpack-dev-server webpack-cli @swc/core @swc/helpers browserslist postcss
yarn add -D @workleap/webpack-configs @workleap/swc-configs @workleap/browserslist-config webpack webpack-dev-server webpack-cli @swc/core @swc/helpers browserslist postcss typescript
yarn add @squide/core @squide/react-router @squide/webpack-module-federation react react-dom react-router-dom
```
+++ npm
```bash
npm install -D @workleap/webpack-configs @workleap/swc-configs webpack webpack-dev-server webpack-cli @swc/core @swc/helpers browserslist postcss
npm install -D @workleap/webpack-configs @workleap/swc-configs @workleap/browserslist-config webpack webpack-dev-server webpack-cli @swc/core @swc/helpers browserslist postcss typescript
npm install @squide/core @squide/react-router @squide/webpack-module-federation react react-dom react-router-dom
```
+++

!!!warning
While you can use any package manager to develop an application with `@squide`, it is highly recommended that you use [PNPM](https://pnpm.io/) as the following guide has been developed and tested with PNPM.
!!!

## 2. Setup the application

### Application structure
Expand All @@ -49,6 +54,17 @@ host
├── swc.build.js
├── webpack.dev.js
├── webpack.build.js
├── package.json
```

### package.json

Then, ensure that you are developing your application using [ESM syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) by specifying `type: module` in your `package.json` file:

```json host/package.json
{
"type": "module"
}
```

### Async boundary
Expand All @@ -73,7 +89,8 @@ To learn more about this async boundary and the `bootstrap.tsx` file, read the f

Then, instanciate the shell [Runtime](/reference/runtime/runtime-class.md) and [register the remote module](/reference/registration/registerRemoteModules.md) (the configuration of the remote module will be covered in the [next section](create-remote-module.md)):

```tsx !#23,13-15,18-20 host/src/bootstrap.tsx
```tsx !#14-16,19-21,24 host/src/bootstrap.tsx
import { Suspense } from "react";
import { createRoot } from "react-dom/client";
import { ConsoleLogger, RuntimeContext, Runtime } from "@squide/react-router";
import { registerRemoteModules, type RemoteDefinition } from "@squide/webpack-module-federation";
Expand All @@ -96,13 +113,15 @@ const context: AppContext = {
};

// Register the remote module.
registerRemoteModules(Remotes, runtime, context);
registerRemoteModules(Remotes, runtime, { context });

const root = createRoot(document.getElementById("root"));
const root = createRoot(document.getElementById("root")!);

root.render(
<RuntimeContext.Provider value={runtime}>
<App />
<Suspense fallback={<div>Loading...</div>}>
<App />
</Suspense>
</RuntimeContext.Provider>
);
```
Expand All @@ -112,7 +131,7 @@ root.render(
Then, [retrieve the routes](/reference/runtime/useRoutes.md) that have been registered by the remote module and create a router instance:

```tsx !#10,13,17 host/src/App.tsx
import { lazy, useMemo } from "react";
import { useMemo } from "react";
import { RouterProvider, createBrowserRouter } from "react-router-dom";
import { useRoutes } from "@squide/react-router";
import { useAreRemotesReady } from "@squide/webpack-module-federation";
Expand All @@ -124,7 +143,7 @@ export function App() {
const isReady = useAreRemotesReady();

// Retrieve the routes registered by the remote modules.
const routes = useRoutes(runtime);
const routes = useRoutes();

// Create the router instance with an home page and the remote module routes.
const router = useMemo(() => {
Expand All @@ -145,24 +164,26 @@ export function App() {

// Display a loading until the remote modules are registered.
if (!isReady) {
return <Loading />;
return <div>Loading...</div>;
}

// Render the router.
return (
<RouterProvider
router={router}
fallbackElement={<Loading />}
fallbackElement={<div>Loading...</div>}
/>
);
}
```

And finally, create the `<Home>` component:

```tsx host/src/Home.tsx
export function Home() {
return (
<div>Hello from the Home page!</div>
)
);
}
```

Expand Down Expand Up @@ -206,7 +227,7 @@ const renderSection: RenderSectionFunction = (elements, index, level) => {
);
};

export default function RootLayout() {
export function RootLayout() {
// Retrieve the navigation items registered by the remote modules.
const navigationItems = useNavigationItems();

Expand All @@ -225,7 +246,7 @@ export default function RootLayout() {
## 3. Configure webpack

!!!info
`@squide` webpack configuration is built on top of [@workleap/webpack-configs](https://gsoft-inc.github.io/wl-web-configs/webpack/), [@workleap/browserslist-config](https://gsoft-inc.github.io/wl-web-configs/browserslist/) and [@workleap/swc-configs](https://gsoft-inc.github.io/wl-web-configs/swc/). If you are having issues with the configuration of these tools, have a look at their documentation websites.
`@squide` webpack configuration is built on top of [@workleap/webpack-configs](https://gsoft-inc.github.io/wl-web-configs/webpack/), [@workleap/browserslist-config](https://gsoft-inc.github.io/wl-web-configs/browserslist/) and [@workleap/swc-configs](https://gsoft-inc.github.io/wl-web-configs/swc/). If you are having issues with the configuration of these tools, refer to the tools documentation websites.
!!!

### HTML template
Expand Down Expand Up @@ -262,7 +283,7 @@ import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc();

export default defineDevConfig(targets);
export const swcConfig = defineDevConfig(targets);
```

Then, open the `webpack.dev.js` file and use the [defineDevHostConfig](/reference/webpack/defineDevHostConfig.md) function to configure webpack:
Expand Down Expand Up @@ -291,7 +312,7 @@ import { browserslistToSwc, defineBuildConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc();

export default defineBuildConfig(targets);
export const swcConfig = defineBuildConfig(targets);
```

Then, open the `webpack.build.js` file and use the [defineBuildHostConfig](/reference/webpack/defineBuildHostConfig.md) function to configure webpack:
Expand All @@ -309,6 +330,28 @@ export default defineBuildHostConfig(swcConfig, "host", "http://localhost:8080/"
If you are having issues with the wepack configuration that are not related to module federation, refer to the [@workleap/webpack-configs documentation](https://gsoft-inc.github.io/wl-web-configs/webpack/configure-build/).
!!!

## 4. Try the application :rocket:
## 4. Add CLI scripts

To initiate the development server, add the following script to the application `package.json` file:

```json host/package.json
{
"dev": "webpack serve --config webpack.dev.js"
}
```

To build the application, add the following script to the application `package.json` file:

```json host/package.json
{
"build": "webpack --config webpack.build.js"
}
```

## 5. Try the application :rocket:

Start the application in a development environment using the `dev` script. You should see the home page. Even if the remote module application is not yet available, the host application will gracefully load.

## 6. Sample application

Start the application, and you should see the home page. Even if the remote module application is not yet available, the host application will gracefully load.
For a functional sample of an host application, have a look at the `@sample/host` application of the `@squide` sandbox on [GitHub](https://github.com/gsoft-inc/wl-squide/tree/main/sample/host).
109 changes: 93 additions & 16 deletions docs/getting-started/create-local-module.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,22 +20,29 @@ Let's add a local module to demonstrate how it's done!
## 1. Install the packages

Create a new project (we'll refer to ours as `local-module`), then open a terminal at the root of the new solution and install the following packages:
Create a new application (we'll refer to ours as `local-module`), then open a terminal at the root of the new solution and install the following packages:

+++ pnpm
```bash
pnpm add -D @workleap/tsup-configs tsup typescript
pnpm add @squide/core @squide/react-router react react-dom react-router-dom
```
+++ yarn
```bash
pnpm add -D @workleap/tsup-configs tsup typescript
yarn add @squide/core @squide/react-router react react-dom react-router-dom
```
+++ npm
```bash
pnpm add -D @workleap/tsup-configs tsup typescript
npm install @squide/core @squide/react-router react react-dom react-router-dom
```
+++

!!!warning
While you can use any package manager to develop an application with `@squide`, it is highly recommend that you use [PNPM](https://pnpm.io/) as the following guide has been developed and tested with PNPM.
!!!

## 2. Setup the application

### Application structure
Expand All @@ -47,33 +54,47 @@ local-modules
├── src
├──── register.tsx
├──── Page.tsx
├── tsup.dev.ts
├── tsup.build.ts
├── package.json
```

### Package configuration
### package.json

Then, ensure that you are developing your module using [ESM syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) by specifying `type: module` in your `package.json` file:

```json local-module/package.json
{
"type": "module"
}
```

Then, add the following fields to the `package.json` files:
Then, configure the package to be shareable by adding the `name`, `version`, and `export` fields to the `package.json` file:

```json !#2,4 local-module/package.json
```json local-module/package.json
{
"name": "@sample/local-module",
"version": "0.0.1",
"main": "dist/register.js"
"exports": {
".": {
"import": "./dist/register.js",
"types": "./dist/register.d.ts",
"default": "./dist/register.js"
}
}
}
```

### Routes and navigation items registration

Then, register the local module [routes](/reference/runtime/runtime-class.md#register-routes) and [navigation items](/reference/runtime/runtime-class.md#register-navigation-items):

```tsx !#8-13,15-20 local-module/src/register.tsx
import { lazy } from "react";
import { registerRoutes, registerNavigationItems, type ModuleRegisterFunction, type Runtime } from "@squide/react-router";
```tsx !#6-11,13-18 local-module/src/register.tsx
import type { ModuleRegisterFunction, Runtime } from "@squide/react-router";
import type { AppContext } from "@sample/shared";
import { Page } from "./Page.tsx";

const Page = lazy(() => import("./Page"));

export const register: ModuleRegisterFunction = (runtime: Runtime, context: AppContext) => {
export const register: ModuleRegisterFunction<Runtime, AppContext> = (runtime: Runtime, context: AppContext) => {
runtime.registerRoutes([
{
path: "/local/page",
Expand All @@ -90,17 +111,29 @@ export const register: ModuleRegisterFunction = (runtime: Runtime, context: AppC
}
```

And finally, create the `<Page>` component:

```tsx local-module/src/Page.tsx
export default function Page() {
export function Page() {
return (
<div>Hello from Local/Page!</div>
)
);
}
```

## 3. Register the local module

Go back to the `host` application and [register the local module](/reference/registration/registerLocalModules.md). Don't forget to add a dependency in the host application `package.json` file.
Go back to the `host` application add a dependency to the `@sample/local-module` package in the host application `package.json` file:

```json host/package.json
{
"dependencies": {
"@sample/local-module": "0.0.1"
}
}
```

Then, [register the local module](/reference/registration/registerLocalModules.md):

```tsx !#5,27 host/src/bootstrap.tsx
import { createRoot } from "react-dom/client";
Expand Down Expand Up @@ -140,6 +173,50 @@ root.render(
);
```

## 4. Try the application :rocket:
## 4. Configure tsup

### Development configuration

To configure tsup for a **development** environment, open the `tsup.dev.ts` file and copy/paste the following code:

```ts local-module/tsup.dev.ts
import { defineDevConfig } from "@workleap/tsup-configs";

export default defineDevConfig();
```

### Build configuration

To configure tsup for a **build** environment, open the `tsup.build.ts` file and copy/paste the following code:

```ts local-module/tsup.build.ts
import { defineBuildConfig } from "@workleap/tsup-configs";

export default defineBuildConfig();
```

## 5. Add CLI scripts

To initiate the development server, add the following script to the application `package.json` file:

```json local-module/package.json
{
"dev": "tsup --config ./tsup.dev.ts"
}
```

To build the module, add the following script to the application `package.json` file:

```json local-module/package.json
{
"build": "tsup --config ./tsup.build.ts"
}
```

## 6. Try the application :rocket:

Start the `host`, `remote-module` and `local-module` applications in development mode using the `dev` script. You should now notice an additional link in the navigation menu. Click on the link to navigate to the page of your new **local** module!

## 7. Sample module

Start both applications, and you should now notice a third link in the navigation menu. Click on the link to navigate to the page of your new local module!
For a functional sample of a **local** module application, have a look at the `@sample/local-module` application of the `@squide` sandbox on [GitHub](https://github.com/gsoft-inc/wl-squide/tree/main/sample/local-module).
Loading

0 comments on commit a4d4a37

Please sign in to comment.