What Β· Quick Setup Β· Features Β· Development Β· Planning Β· Contributions
This is a WIP prototype containing all of our project and component generators, as well as the UIDL schemas and validators. While we have some working examples, it shouldn't be considered production ready by any means! Don't hesitate to give us feedback and feel free to contribute in any way!
The code generators are a part of the teleportHQ ecosystem, which we're actively building in an effort to streamline the creation of web and mobile applications. You can read more about our inception in this article.
The code generators are used by our online visual editor (coming soon), a platform that lets you build applications via a familiar design tool interface. The glue between our platform and the code generators is the [UIDL Standard](link coming soon). The UIDL allows us to define user interfaces in an abstract way, independent of any framework or even the web platform itself, which then allows us to convert that abstraction into different flavors of coding (e.g. React, Vue, etc.).
Our philosophy behind the code generators is:
- User interfaces are decomposed into components, hence our focus on component generation
- What can be built with
React
, can also be built withVue
or on top of theWeb Components
standard - we support multiple targets - A project built with the visual editor should have a high standard of quality (performance, security, accessibility included)
- Generated code quality should 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!
You can also read more on our [decision to open source our code generators](link coming soon).
Read more about the [UIDL Standard](link coming soon).
While this will probably remain a monorepo, we'll publish different npm packages for various parts of our code generation ecosystem. For now, there's a single package published under @teleporthq/teleport-code-generators
. So, let's integrate that into your project:
npm install @teleporthq/teleport-code-generators
import { createReactComponentGenerator } from '@teleporthq/teleport-code-generators'
// instantiate a react generator
const reactGenerator = createReactComponentGenerator()
// define a UIDL representation
const componentUIDL = {
"name": "MyComponent",
"node": {
"type": "element",
"content": {
"elementType": "text", // equivalent of the span
"children": [{
"type": "static", // equivalent of the text node inside
"content": "Teleport World!"
}]
}
}
}
// get the code
reactGenerator
.generateComponent(componentUIDL)
.then(result => {
console.log(result.files[0].content)
})
.catch(err => {
console.log(err)
})
The code output from this snippet would be
import React from "react"
const MyComponent = props => {
return <span>Teleport World!</span>
}
export default MyComponent
You can find more advanced UIDL samples to play with here.
This repo contains multiple modules that will soon be available as individual npm
packages. There are two types of generators available: component and project generators. Component generators take a simple ComponentUIDL input and return the code according to the specific generator flavors (e.g. React + StyledJSX, Vue, etc.). Project generators operate on ProjectUIDLs and will return a complete structure of folders
and files
which then can be written to disk or sent to servers for deployment. The aim of the project generators is to output a working application.
We have official component generators for React
and Vue
, but we also plan on supporting other frameworks and standards as soon as possible. Also, React Native
is definitely on our minds, since we've designed the UIDL in such a way that it's agnostic of the web platform.
There are two factory functions exported from our main module, for the React and Vue generators.
import { createReactComponentGenerator } from '@teleporthq/teleport-code-generators'
// define a UIDL representation
const componentUIDL = {
"name": "MyComponent",
"node": {
"type": "element",
"content": {
"elementType": "text",
"children": [{
"type": "static",
"content": "Teleport World!"
}]
}
}
}
/* instantiate a generator, selecting the styled-jsx plugin for handling styles
(other options: CSSModules, JSS, InlineStyles, StyledComponents) */
const reactGenerator = createReactComponentGenerator({ variation: 'StyledJSX' })
// get the code
reactGenerator
.generateComponent(componentUIDL)
.then(result => {
console.log(result.files[0].content)
})
.catch(err => {
console.log(err)
})
Read more about [the API of the component generator](link coming soon).
Read more about [mappings and resolvers](link coming soon).
import { createVueComponentGenerator } from '@teleporthq/teleport-code-generators'
// define a UIDL representation
const componentUIDL = {
"name": "MyComponent",
"node": {
"type": "element",
"content": {
"elementType": "text", // equivalent of the span
"children": [{
"type": "static", // equivalent of the text node inside
"content": "Teleport World!"
}]
}
}
}
// instantiate a vue generator
const vueGenerator = createVueComponentGenerator()
// get the code
vueGenerator
.generateComponent(componentUIDL)
.then(result => {
console.log(result.files[0].content)
})
.catch(err => {
console.log(err)
})
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 (Hooks in React)
- Event Handlers (related to state changes)
- Repeat structures (.map in React, v-for in Vue)
We have official project generators for the two different frameworks we're supporting so far. For React
, we can generate a project based on a React
and React-Router
template, or we can generate a project on top of Next.js
. For Vue
, we have a standard Vue
app, build with the vue-cli
and a generator for Nuxt
.
Project generators rely on the component generators and on the structure of the ProjectUIDL
to figure out how many files to create and where to create them. Each project generator has its own strategy, based on the particularities of that specific framework/tool.
Coming soon
Coming soon
Coming soon
Coming soon
Besides the regular files and folders generated at the end of the process, project generators are also taking care of:
- Extracting all external dependencies and adding them to the
package.json
- Creating the entry point for each application (it can be an
index.html
or something that is framework specific) - Generating a web manifest for PWA support
Full documentation coming soon.
A few useful links to get you up to speed with the entire teleport ecosystem:
- [Component](link coming soon) and [Project](link coming soon) JSON Schemas
- [Full Documentation](link coming soon)
- [Introducing the new Generators](link coming soon)
- [Playground link](link coming soon)
This project uses:
- TypeScript for type safety and easy refactoring
- lerna for managing the monorepo with multiple npm packages
- jest for all types of tests and for calculating the code coverage
- verdaccio for testing out the published packages in a local environment
In order to give it a spin locally, we recommend using yarn
, as it integrates better with lerna
and all the contributors are using:
yarn
This installs the dependencies in the root folder, but also creates the symlinks between the independent modules inside the packages
folder.
To complete the lerna setup, you need to run:
yarn build
This will run the build
task inside each individual package, creating the output lib
folder.
Running the test suite:
yarn test
yarn test:coverage
Additionally, we have a separate project inside the solution that is testing the project generator packages. You will find this in the /examples/project-exporters
folder. This solution however, requires the packages to be published on a registry. For testing the immediate changes on a project generator, we rely on verdaccio
as a private local npm server.
To use verdaccio you have to install it globally and then run it (starts the server on port 4873 by default):
yarn global add verdaccio
verdaccio
You need to setup a user on your local server (follow the instructions):
npm adduser --registry http:https://localhost:4873
Finally, you can publish all the packages with lerna on the local verdaccio server:
yarn local:publish
If you navigate to https://localhost:4873
you should see your published packages.
Now it's time to move to the project exporter:
cd examples/project-exporters
yarn
After the dependencies are installed (including the teleporthq packages from verdaccio), you can generate the projects locally, with one of the four tasks:
npm run create-react-basic
npm run create-react-next
npm run create-vue-basic
npm run create-vue-nuxt
Files and folders for each template are generated after you run the corresponding npm task in /examples/projects-exporters/<project-template>/dist
.
Please open an issue for any irregularity, potential bug that you find while running this, or if you simply have any questions or curiosities about this project.
It's not just our code that's open source, we're also planning the development of the code generators on GitHub. We already have a number of issues opened and we expect further contributions on this.
We're especially interested in opening discussions around the issues tagged with the proposal
label.
We also have a couple of milestone down the line:
We plan on releasing this around mid May 2019. Most of the issues tackled during this milestone can be found here.
Our official release will be a switch to version 1.0
. ETA for this is around mid June/July 2019. Hopefully, by then, we'll have more people contributing to the code generators.
We'd be super happy to have community involvement around this project. We strongly believe in the power of open 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):
This project follows the all-contributors specification. Contributions of any kind welcome!
Reach out to us on any of these channels:
- π§ Write an Email
- π¦ Drop a message on twitter
- βΉοΈ Website