Getting started

You're a bit early 😅

nstal is brand new and is not ready for production:

  • The idea of automating a tutorial is new. Therefore it is hard to tell if nstal's architecture is the right one or if it should be refined. For this reason, the API may change. Think breaking changes.
  • The nstal CLI suffers from important security issues, since it allows an nstaller to run any command on a local system. There are a lot of solutions to this problem, some simple, some much harder to implement. But for now, it is just not safe to ask random people to run npx nstal on their laptops.
  • The project is unpolished, it lacks proper doc, etc.

nstal is not for you (yet) if...

... you are looking for a directory of ready-to-use nstallers. Although there are nstallers for setting up nstal or configure Tailwind, this is not the point of the project yet.

... you want to create your nstal-powered personal blog right away. The project will undergo breaking changes and your blog will stop working overnight.

nstal is for you if...

... you like the idea of automated tutorials and install procedures and you want to be involved in nstal's development.

... you want to create your nstal-powered personal blog as soon as possible, and you want to experiment and get ready. If it is successful, nstal could be the next big thing in the tech blogging area. So this approach totally makes sense.

How it works 🛠ïļ

nstal is a set of React components you can use to write tutorial-like content. Unlike static tutorials, nstal-aware pages, called nstallers, can actually run what they describe. While a classic tutorial says "Create util.js", an nstaller can also do it.

To achieve this, nstal needs to connect to a local agent running on the local machine. This is done via nstal, a CLI tool. The React components in the page connect to this tool using WebSockets. As soon as the connection is established, the nstaller becomes able to run the instructions it documents.

Anatomy of an nstaller ðŸĶī

Although nstal components can be used in a vanilla React app, they are well-suited for MDX. As MDX is Markdown + JSX, you can write the tutorial regular content using Markdown, while using JSX for the nstal bits.

# A small tutorial

Well done, it's over!

Nstaller

The Nstaller component wraps the nstaller content. It provides context and React hooks to the inner nstal components.

In addition, it provides the components to render the various actions. It is a bit similar to the MDX Provider.

import { Nstaller } from '@nstaldev/react-core'
import { NstalReactComponents } from '@nstaldev/react-components'

# A small tutorial

Well done, it's over!

export default ({ children }) => (
  <Nstaller components={NstalReactComponents}>
    {children}
  </Nstaller>
)

Action

nstaller have actions. An action is an atomic step that should be performed, either manually of automatically. For example, "install xyz package", "create some-file.js", "run yarn dev"...

An action is responsible for rendering its content on the page so the nstaller looks like a standalone tutorial that can be consummed like any regular content. The action also interacts with the agent to fulfil its purpose.

import { Nstaller, CreateFile } from '@nstaldev/react-core'
import { NstalReactComponents } from '@nstaldev/react-components'

# A small tutorial

<CreateFile
  path="README.md"
  content="Hello from nstal!"
/>

Well done, it's over!

export default ({ children }) => (
  <Nstaller components={NstalReactComponents}>
    {children}
  </Nstaller>
)

Connector

The connector handles the connection. It both gives instructions to the reader, such as the CLI command to run, and provides the connection to the nstaller context.

import { Nstaller, CreateFile, Connector } from '@nstaldev/react-core'
import { NstalReactComponents } from '@nstaldev/react-components'

# A small tutorial

<Connector />

<CreateFile
  path="README.md"
  content="Hello from nstal!"
/>

Well done, it's over!

export default ({ children }) => (
  <Nstaller components={NstalReactComponents}>
    {children}
  </Nstaller>
)

Milestone

A Milestone is displayed when a certain point is reached:

import { Nstaller, CreateFile, Connector, Milestone } from '@nstaldev/react-core'
import { NstalReactComponents } from '@nstaldev/react-components'

# A small tutorial

<Connector />

<CreateFile
  path="README.md"
  content="Hello from nstal!"
/>

<Milestone>
  Well done, it's over!
</Milestone

export default ({ children }) => (
  <Nstaller components={NstalReactComponents}>
    {children}
  </Nstaller>
)

Tutorial 🧑‍🎓

Setup nstal with Next.js and MDX