Code Generators v0.21.12 - Beta!

What · Quick Setup · Ecosystem · Documentation · Development · Planning · Contributions

We are not far from thefirst official versionof the code generators, but meanwhile, keep in mind that some of the parts of the ecosystem are experimental.

🤔 What is this?

teleportHQis a low-code platform that enables teams to build applications via a familiar design tool interface, in real-time.

This repository holds the code generators that power thevisual editorof the platform.

teleport-home.mp4

The glue between the platform and the code generators is theUIDL Standard.TheUIDLdefines theuser interfacesin anabstractway, independent of any framework or even the web platform itself. Starting from the UIDL, you can convert that abstraction into different flavors of coding (e.g. React, Vue, WebComponents etc.).

These code generators are part of a larger ecosystem, which we're actively building in an effort to streamline the creation of web applications. You can read more about our inception inthis article.

The philosophy behind the code generators is:

• User interfaces are decomposed intocomponents,hence the focus on component generation
• What can be built withReact,can also be built withVueor on top of theWeb Componentsstandard - we support multiple targets
• A project built with the visual editor should have ahigh standard of quality(performance, security, accessibility included)
• Generatedcode qualityshould be as high as possible, so that any developer could pick up the work from there on and enhance the project
• The code generation architecture is open and extendable, we invite everyone to contribute!

Read more about theUIDL Standard.

🚀 Quick Setup

The easiest way to jump into theteleport ecosystemis to try out one of the pre-configuredcomponent generators:

npm install @teleporthq/teleport-component-generator-react
npm install @teleporthq/teleport-component-generator-vue
npm install @teleporthq/teleport-component-generator-angular

or using yarn:

yarn add @teleporthq/teleport-component-generator-react
yarn add @teleporthq/teleport-component-generator-vue
yarn add @teleporthq/teleport-component-generator-angular

For generating a simple component, you have to start from acomponent UIDL:

{
"name":"My First Component",
"node":{
"type":"element",
"content":{
"elementType":"text",
"children":[
{
"type":"static",
"content":"Hello World!"
}
]
}
}
}

Using the pre-configured component generators is as easy as calling anasyncfunction:

importReactGeneratorfrom'@teleporthq/teleport-component-generator-react'

constuidl={...}// your sample here

const{files}=awaitReactGenerator.generateComponent(uidl)
console.log(files[0].content)

The console output will be something like:

importReactfrom'react'

constMyFirstComponent=(props)=>{
return<span>Hello World!</span>
}

exportdefaultMyFirstComponent

For other frameworks, just switch the package:

importVueGeneratorfrom'@teleporthq/teleport-component-generator-vue'

constuidl={...}// your sample here

const{files}=awaitVueGenerator.generateComponent(uidl)
console.log(files[0].content)

The console output will be something like:

<template>
<span>Hello World!</span>
</template>

<script>
exportdefault{
name:'MyFirstComponent',
}
</script>

You can play with the UIDL structure and also observe the generated code inthe online REPL.While there, can also check different examples of components written in the UIDL format.

🌍 Ecosystem

The teleport ecosystem consists ofthreemain categories of packages:component generators,project generatorsandproject packers.

Component Generators

We haveofficialcomponent generators fora couple of popular web frontend frameworks.Check out theofficial docsfor an in depth understanding of the architecture behind the component generators.

All the component generators are exposing an instance of theteleport-component-generatorpackage. You can also install this package and build your own generator withplugins,mappingsandpostprocessors.

In the docs, you'll find a complete guide on how tobuild your custom component generator.

Flavors

• teleport-component-generator-react- with styling:css-modules,styled-components,styled-jsx,etc.
• teleport-component-generator-vue- generating standard.vuefiles
• teleport-component-generator-angular- generates.ts,.htmland.cssfiles
• teleport-component-generator-html- (experimental)
• teleport-component-generator-svelte- (coming soon)

Capabilities

Here's a list of functionalities that the UIDL and the component generators are supporting at the moment, besides the obvious presentational layer:

• Dynamic values (props, state) inside html nodes or at attribute level
• Type definitions for component props (PropTypes in React, props in Vue)
• External dependencies definition
• Simple component state (using hooks in React, component instance in Vue)
• Event Handlers (related to state changes)
• Repeat structures (.map in React, v-for in Vue)
• Support for slots

Project Generators

Project generators rely on aProjectUIDLinput and on aproject strategy.TheProjectUIDLwill contain all the information about routing, pages, components and global settings. The strategy will tell the generators where to put each file and which component generator to use.

The generators will output an abstract structure with folders and files, without writing anything to disk. The project packer is tasked with taking the output of a project generator and publishing it somewhere.

Check the official guides onhow to use an existing project generatororhow to create your custom configuration

Flavors

• teleport-project-generator-react-react+react-routerandcss-moduleson top ofcreate-react-app
• teleport-project-generator-next- based onNext.js
• teleport-project-generator-vue- with a structure starting from thevue-cli
• teleport-project-generator-nuxt- based onNuxt.js
• teleport-project-generator-angular- based on theangular-cli
• teleport-project-generator-html(experimental)

Capabilities

Besides the regular files and folders generated at the end of the process, project generators are also taking care of:

• Support for global settings, meta tags, style, scripts, etc.
• Extracting all external dependencies and adding them to thepackage.json.
• Creating the entry point for each application (it can be anindex.htmlor something that is framework specific).
• Creating a routing file for the client routes of the project.
• Generating a web manifest for PWA support.

Project Packers

Once a generator created the code for the components and pages, theproject packerwill take that output, put it on top of an existingproject template,add any localassetsrequired and then will pass the entire result to apublisher.The publishers are specialized in deploying the entire folder structure to a 3rd party likevercelorgithub,or in creating an in-memoryzipfile or simply writing the folder todisk.

Publishers

• teleport-publisher-vercel
• teleport-publisher-github
• teleport-publisher-codesandbox
• teleport-publisher-zip
• teleport-publisher-disk
• teleport-publisher-netlify(coming soon)

Further Reading

A few useful links to get you up to speed with the entireteleportecosystem:

• Full Documentation
• ComponentandProjectJSON Schemas
• Online REPL

💻 Development

This project uses:

• TypeScriptfor type safety and easy refactoring
• lernafor managing the monorepo with multiple npm packages
• jestfor all types of tests and for calculating the code coverage

In order to give it a spin locally, we recommend usingyarn,as it integrates better withlernaand all the contributors are using it:

yarn

This installs the dependencies in the root folder, but also creates the symlinks between the independent modules inside thepackagesfolder.

To complete the lerna setup, you need to run:

yarn build

This will run thebuildtask inside each individual package, creating the outputlibfolder. We have two outputs for each package:cjs- common js style modules andesm- modern es modules. If you want to speed up your build time, you can run justbuild:cjsto avoid theesmbuild.

Running the test suite:

yarn test
yarn test:coverage

Furthermore, there's aprivatepackage inside the lerna folder calledteleport-test.That packages can be used totestthe code/file generation process with any flavor of project/component generator. In order to give it a spin you will have to:

cd packages/teleport-test
npm run standalone

The standalone version uses theteleport-code-generatorpackage and the statically declared templates. To test with the github templates and the custom packer instance, you have to:

cp config.example.json config.json

You will have to replace the placeholder withyour own github token. Then you can run it with:

npm run packer

This version of the packer uses the UIDLs from theexamples/uidl-sample.If the process runs successfully, you will see the responoses from the project packer in the format:{ success: true, payload: 'dist' }.The task uses theteleport-publisher-diskpackage and generates four different project files in thedistfolder.

Pleaseopen an issuefor any irregularity, potential bug that you find while running this, or if you simply have any questions or curiosities about this project.

🤖 Planning

It's not just our code that's open source, we're also planning the development of the code generators on GitHub. We havea number of issuesopened and we expect further contributions on this.

We're especially interested in opening discussions around the issues tagged with thediscussionlabel.

Official Release

The official release will be a switch to version1.0.ETA for this is around the end of 2019.

💕 Contributions

We'd be super happy to havecommunityinvolvement around this project. We strongly believe in the power ofopen source,so we're planning on building the best possible code generators, together with the entire development community.

We envision different types of involvement from this point on:

• Trying out the generators and reporting back any bugs and potential points of improvement
• Contributing to the existing issues, either on the core modules or on the existing generators and plugins
• Exploring and building new plugins for the existing generators
• Exploring and building new generators based on the existing architecture

Thanks goes to these wonderful people (emoji key):

Alex Moldovan 💻📖🤔	Vlad Nicula 💻🤔	Paul BRIE 🐛📖🤔	mihaitaba 🎨📖	Mihai Serban 💻	Jaya Krishna Namburu 💻🐛	Anamaria Oros 💻
ovidiuionut94 💻	alexpausan 💻	Mihai Sampaleanu 💻🐛	Utwo 💻	andreiTnu 💻	Xavier Cazalot 💻	Chavda Bhavik 💻
Eliza Nitoi 💻	TudorCe 🐛	Dorottya Ferencz 🐛	William Gounot 💻

This project follows theall-contributorsspecification. Contributions of any kind welcome!

✍️ Contact

Reach out to us on any of these channels:

• 📧Write an Email
• 💻Discord
• 🐦Drop a message on twitter
• ℹ️Website