Skip to content
richytongPublic

Repository files navigation

Arche

arche-logo

Arche (/ˈɑːrki/; Ancient Greek: ἀρχή) is a Greek word with primary senses "beginning", "origin" or "source of action" (ἐξ' ἀρχῆς: from the beginning, οr ἐξ' ἀρχῆς λόγος: the original argument), and later "first principle" or "element".

Source code: GitHub | License: CFOSS

Node.js CI codecov npm version

Vanilla Microfrontends

A web page is a render of an HTML document.

An HTML document loads JavaScript scripts and CSS stylesheets.

JavaScript scripts can load JavaScript scripts.

Principles:

  • Front end development for the web should be done in HTML, CSS, and JavaScript.

Getting Started

Vanilla microfrontends starts with an HTML document. Whenever a browser navigates to a web page, the first file it downloads and reads is the HTML document of the web page.

Here's a project structure. The public directory will have all of the files that will be public to the world wide web.

public/
    index.html
    styles.css
    index.js

The HTML document of a web page loads JavaScript scripts and CSS stylesheets. JavaScript scripts are defined with <script></script> tags, and CSS stylesheets with <link> tags. Add this to index.html.

The HTML document is read line by line, from top to bottom.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Welcome to Vanilla Microfrontends.</title>

  <link rel="stylesheet" href="/styles.css" />
</head>
<body>
  <h1>Welcome to Vanilla Microfrontends.</h1>
  <p>This HTML document is the first file a browser downloads and reads when it navigates to this web page.</p>

  <div id="click-example">
    <p>You clicked 0 times.</p>
    <button>Click</button>
  </div>

  <script src="https://cdn.jsdelivr.net/npm/arche"></script>
  <script src="/index.js"></script>
</body>
</html>

CSS stylesheets are downloaded and read right after the HTML document. Add this to styles.css.

body {
  color: #FFF;
  background-color: #7FB665;
}

h1 {
  font-size: 32px;
}

p {
  font-size: 14px;
}

JavaScript scripts are run from where they are defined in the HTML. Add this to index.js.

console.log("Welcome to Vanilla Microfrontends.")

const DocumentElement = Arche(document)
const { P } = DocumentElement

const p2 = P("This element was added from index.js.")

document.body.appendChild(p2)

const p1 = document.querySelector("#click-example > p")
const button = document.querySelector("#click-example > button")

let value = 0

button.addEventListener("click", () => {
  value += 1
  p1.innerHTML = `You clicked ${value} times.`
})

Now all you have to do to see the website you just created is serve the public folder. I recommend installing the static-web-server command line tool from Static Web Server.

Install static-web-server with the following command:

curl --proto '=https' --tlsv1.2 -sSfL https://get.static-web-server.net | sh

Now you can serve the public folder. Serve the public folder with the following command:

static-web-server --port=8080 --root=./public

Finally, navigate to http://localhost:8080/.

Tips

Import Statements

To import a JavaScript file in another JavaScript file, use an import statement.

import ClickExample from "./ClickExample.js"

Dynamic Imports

To dynamically import a module, use the import keyword as a function.

async function () {
  const myModule = await import("/my-module.js")
}

Getting Started with React

React is a library and paradigm for creating web and native interfaces in JavaScript. If you are new to React, please watch this video.

Here is a project structure for a website made with React.

public/
    index.html
    styles.css
    ClickExample.js
    index.js

Add this to the index.html file.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Welcome to Vanilla Microfrontends with React.</title>

  <link rel="stylesheet" href="/styles.css" />
</head>
<body>
  <div id="react-root"></div>

  <script src="https://cdn.jsdelivr.net/npm/arche"></script>
  <script src="https://cdn.jsdelivr.net/npm/react/umd/react.production.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/react-dom/umd/react-dom.production.min.js"></script>
  <script src="/index.js" type="module"></script>
</body>
</html>

Add this to styles.css.

body {
  color: #FFF;
  background-color: #7FB665;
}

h1 {
  font-size: 32px;
}

p {
  font-size: 14px;
}

#click-example {
  margin-top: 20px;
}

Add this to ClickExample.js.

const ReactElement = Arche(React)
const { Div, P, Button } = ReactElement
const { useState } = React

const ClickExample = ReactElement(() => {
  const [count, setCount] = useState(0)

  return Div({ id: "click-example" }, [
    P(`You clicked ${count} times`),
    Button({
      onClick() {
        setCount(count + 1)
      },
    }, "Click me"),
  ])
})

export default ClickExample

Add this to index.js.

import ClickExample from "./ClickExample.js"

const ReactElement = Arche(React)
const { Div, H1, P } = ReactElement

const Root = ReactElement(() => {
  return [
    H1("Welcome to Vanilla Microfrontends with React."),
    P("All of the content on this page was added with React."),
    ClickExample(),
  ]
})

ReactDOM.render(Root(), document.getElementById("react-root"))

Serve the public folder.

static-web-server --port=8080 --root=./public

Navigate to http://localhost:8080/.

React Tips

Global

Set ReactElement globally for a better developer experience.

// global.js
const ReactElement = Arche(React)

window.ReactElement = ReactElement

for (const elementName in ReactElement) {
  window[elementName] = ReactElement[elementName]
}

// set missing elements
window.Aside = ReactElement("aside")
window.Svg = ReactElement("svg")
window.Path = ReactElement("path")

React Context

To have React Context with Arche, wrap YourContext.Provider with ReactElement and supply value as a prop, specifying children in the next argument.

JSX example:

function ArticleWrapper () {
  const [theme, setTheme] = React.useState(themes[0])

  return (
    <ThemeContext.Provider value={{
      theme,
      changeTheme: setTheme
    }}>
      <ThemeSwitcher />
      <Article />
    </ThemeContext.Provider>
  )
}

Translates to the following with Arche:

const ArticleWrapper = ReactElement(() => {
  const [theme, setTheme] = React.useState(themes[0])

  return ReactElement(ThemeContext.Provider)({
    value: { theme, changeTheme: setTheme },
  }, [ThemeSwitcher(), Article()])
})

React Fragments

For React fragments (<>), just return an array.

const ReactElement = Arche(React)
const { Div, H1, Img } = ReactElement

const Placeholders = ReactElement(() => [
  Img({ src: "https://placehold.co/300x150", alt: "placeholder" }),
  Img({ src: "https://placehold.co/300x150", alt: "placeholder" }),
])

const Root = ReactElement(() => [
  H1("Fragment Example"),
  Placeholders(),
])

ReactDOM.render(Root(), document.getElementById("react-root"))

Working with Styled Components

To install Styled Components, add the following script to your Arche and React scripts.

<script src="https://cdn.jsdelivr.net/npm/styled-components/dist/styled-components.min.js"></script>

Arche accepts a styled option from css-in-js libraries like Styled Components to enable a css prop on ReactElement and TypedReactElement.

const ReactElement = Arche(React, { styled })

Elements can now specify a css prop for css-in-js.

const ReactElement = Arche(React, { styled })
const { Div, H1, P } = ReactElement

const MyComponent = ReactElement(() => {
  return Div({
    css: `
      height: 500px;
      width: 100%;
      background-color: pink;
    `,
  }, [
    H1("Styled Example"),
    P("Text"),
  ])
})

ReactDOM.render(MyComponent(), document.getElementById("react-root"))

Server-Side Rendering

For server-side rendering, see ArcheHTML.

Vanilla Microfrontends Ecosystem

Here are some awesome libraries that are part of the vanilla microfrontends ecosystem.

Contributing

Your feedback and contributions are welcome. If you have a suggestion, please raise an issue. Prior to that, please search through the issues first in case your suggestion has been made already. If you decide to work on an issue, please create a pull request.

Pull requests should provide some basic context and link the relevant issue. If you are interested in contributing, the help wanted tag is a good place to start.

For more information please see CONTRIBUTING.md

License

Arche is distributed under the CFOSS License.

Support

  • minimum Node.js version: 14
  • minimum Chrome version: 63
  • minimum Firefox version: 57
  • minimum Edge version: 79
  • minimum Safari version: 11.1

Releases

Packages

Used by

Contributors

Languages