Coder Social home page Coder Social logo

uvacoder / livecodes Goto Github PK

View Code? Open in Web Editor NEW

This project forked from live-codes/livecodes

0.0 0.0 0.0 31.83 MB

Code playground that runs in the browser!

Home Page: https://livecodes.io

License: MIT License

JavaScript 1.23% HTML 11.02% TypeScript 81.95% CSS 1.26% SCSS 4.54%

livecodes's Introduction

LiveCodes

Code pens that run locally!

A powerful frontend coding playground that runs totally on the client and can be hosted on any static file server.

Try it now on livecodes.io

TL;DR: Getting started

Codacy Badge

Deploy to DO

Feature Summary:

  • Monaco editor (the beautiful code editor that powers VS Code)
  • Prettier code formatting
  • Supports many languages (HTML, Markdown, Pug, AsciiDoc, CSS, SCSS, SASS, Less, Stylus, JavaScript, TypeScript, JSX, CoffeeScript and more to come)
  • Emmet tab completion
  • Autoprefixer
  • All code compiling/transpiling occurs on the fly on the client, so works on any static server.
  • Immediate results with no server rounds
  • Conditional loading of modules (only the features used are downloaded)
  • Templates: Starter templates and user-defined templates
  • Allows adding external stylesheets and/or scripts
  • Allows importing npm modules that can be referenced directly without a build step (using the great skypack.dev)
  • Allows importing strongly-typed local typescript modules with full code completion and intellisense.
  • CSS Presets (e.g Normalize.css, CSS reset)
  • Can be embedded in regular web pages
  • Code embeds allow editing with the immediate preview
  • Resizable split panes (using split.js)
  • Multiple modes: full mode (with split panes), editor only mode and read-only code-block mode
  • Editors can be prefilled by code from github and gitlab (gists and repos) or from your web pages
  • Immediatley recognizes and imports codepens exported to github gists
  • Export/import projects as JSON
  • Export source code as zip file or ready-to-run HTML page with the compiled/transpiled code
  • Export to CodePen and JSFiddle (more to come)
  • Save/open from local storage with optional autosave
  • JS/TS Console (using Luna Console)
  • View compiled code
  • Keyboard shortcuts
  • LiveCodes is under active development with more features to come (see Roadmap)

Table of Contents

What makes LiveCodes different?

The are many great products like CodePen, JSFiddle, JS Bin, JSitor and many others, which LiveCodes does not aim to replace or compete with. On the contrary, it aims to integrate with many of these services as their APIs allow (e.g. import and export).

However, LiveCodes aims to stay as a client-side only app that can be hosted on any static file server. After the initial loading, using the app can be significantly faster than having to wait for server rounds. Any syncing or sharing capabilities would use external services. Having said that, it is an open-source software, and it should not be difficult to implement a backend for such features if you want to extend it as a different project (may be have a look at parse starter).

The other main goal for LiveCodes (in fact, that was the motive for its development), is to provide a feature-rich, easy to use playground that library developers can use for the documentation of their libraries and as a showcase for their products. This includes using the hosted app (livecodes.io), or as a self-hosted option (by including it in their website, or on a separate subdomain for example). Again, being a client-side only app, LiveCodes becomes more convenient for not needing special server requirements.

To have embedded editors using a freely-available open-source software is very handy. That goal also drives the requirement for being able to import local (unpublished) modules with editor auto-completion and intellisense.

LiveCodes uses Monaco editor (VS Code editor), Prettier, Emmet and Autoprefixer among others. Your can import NPM modules without a build step. It feels like a very light weight version of your own local development environment with the intellisense and the auto-completion features. All that is on a browser without having to npm install anything.

LiveCodes uses Monaco editor (VS Code editor), Prettier, Emmet and Autoprefixer among others. You can import NPM modules without a build step. It feels like a very light weight version of your own local development environment with all the intellisense and the auto-completion features, without having to npm install anything;

Important note: Please note that LiveCodes is in early development and may not yet be ready for production use. API may change, and security and performance improvements may still be required. However please take the time to try it. Your feedback and contribution are highly appreciated.

Enough talk, let's get started.

Getting started

There are multiple options:

  • You may just use the hosted app (livecodes.io) and use various methods to add your code like embedded editors, code blocks, "Edit in LiveCodes" and code prefill.

  • One-click deploy to Digital Ocean

  • Download the app from the releases, extract the folder and add it to your website.

  • Fork the repo, clone it. You may wish to use the included setup to publish to github pages:

    npm install
npm run build
npm run serve         # locally serve to http://localhost:8080
npm start             # start local development with code watch, rebuild and live-reload
npm run gh-pages      # publish to github pages

  • An npm package is also planned.

Screenshots

Examples

Please note that most of the examples presented in this section are code samples that were publicly available as code pens and were used for demonstration with no or little modifications.

In fact, most pens on CodePen can be imported with no or minor modifications (See Importing from CodePen)

Settings

Most of the settings can be configured from the UI through the settings menu (accessed from the top right gear icon). Many settings can also be configured by URL querystring parameters.

LiveCodes uses a configuration file (by default at the url: /livecodes.json). This can be changed by the querystring parameter config, for example:

?config=/playground/custom-config.json"

Full documentation for configuration will be available when the API gets stable. Meanwhile, the structure and valid values can be found here. Notice that this is currently subject to change.

Default Editors

By default, the loaded editors use HTML, CSS and Javascript. If you import code, the editors will use the language of the imported files. However, you may wish to load empty editors with other languages without importing code. You can do that with querystring parameters having the extension (or lowercase name) of the languages you want.

For example, to load editors with HTML, SCSS and TypeScript (with Typescript as the active editor), go to:

https://livecodes.io/?ts&scss&html

To load markdown as the active editor, go to:

https://livecodes.io/?md

Templates

New projects can start with a blank template or use any of the provided starter templates (which include starter templates for typescript, react, vue, angular preact, jQuery, bootstrap, tailwind and D3). Alternatively users can save any project as a template (settings menu > save as > Template). It can then be used when starting a new project (settings menu > New > My Templates).

External Stylesheets/Scripts

External CSS stylesheets and JavaScript files can be added to the page from the UI using the settings menu > External CSS/JS.

These are loaded before the editor codes. You can override CSS properties in them. Global javascript variables defined there should be available to your code.

Importing and Exporting your code to other services (e.g. Codepen and Github gists) takes into consiedration the external resources.

Importing NPM Modules

In LiveCodes you can use node-style non-relative imports for node modules like you do in your local development. Yet, there is no build step.

e.g. consider the following code: (try it here)

import { v4 } from 'uuid';

document.body.innerHTML = v4();

If you run it in regular web page, you get this error:

Uncaught TypeError: Failed to resolve module specifier "uuid". Relative references must start with either "/", "./", or "../".

However, in LiveCodes, all non-relative imports are converted on-the-fly to use the great service of skypack.dev.

So

import { v4 } from 'uuid';

gets converted to

import { v4 } from 'https://cdn.skypack.dev/uuid';

You can import React like that: (Demo)

import React, { useState } from 'react';
import ReactDOM from 'react-dom';

It just works without a build step and without you having to worry about. And when you export your code to another service (e.g CodePen or JSFiddle), the full url imports are used, so your code continue to work elsewhere.

It is recommended to use this method for dependencies over using external scripts. The dependencies are explicitly stated in the code. And if you move to a local development environment, your bundler will take care of importing them and doing other optimizations like tree-shaking.

Saving to Device Local Storage

Projects can be locally saved to device using local storage. You can save a project by clicking Save on the settings menu, or simply with the keyboard shortcut Ctrl/Cmd + S. After the initial save, autosave is enabled so that you do not lose code changes. You may disable autosave from the settings menu. It will remain disabled till the next save.

You may also fork the project (save as a new project). Also from the settings menu > Fork, or the keyboard shortcut Ctrl/Cmd + Shift + S.

Previously saved projects can be opened from the settings menu > Open. In that screen you can open/delete any project or delete all.

Please note that the projects are locally saved on the device and are not uploaded to the server.

Exporting Content

Projects in LiveCodes can be exported as:

  • JSON: this is a JSON representation of the project configuration with the project source code included. This allows re-importing or sharing your projects.
  • Source: The source code is exported as separate files in a single zip file. This is your untouched source code which you may wish to open in another code editor.
  • Result: The combined compiled/transpiled code is exported as a ready-to-run HTML file. You may run it by simply opening the file in the browser, or using a simple local http server, for example: 
    npx http-server

Edit in other Services

Currently LiveCodes can export content to CodePen and JSFiddle. This is accessible from the settings menu > Export.

It is planned to support more services. This allows you to move code between different services.

Importing Code (Editor Prefill)

You can prefill editors with code. This can be great for documentation and sharing links with code.

Importing from URL

Most commonly, code is imported from a URL. You can provide the source URL in the UI (settings button > Import), or by adding the URL as a hash to the LiveCodes URL:

(e.g. https://livecodes.io/#https://gist.github.com/hatemhosny/a0a32216df59e53879b7cd83856cdde4)

LiveCodes can detect and automatically load code from multiple sources. Currently the supported sources are:

  • Github gists (imports multiple files in the gist)
  • A directory in a github repo (multiple files)
  • A file in a github repo (imports that single file)
  • Gitlab snippets (imports multiple files in the snippet)
  • A directory in a gitlab repo (multiple files)
  • A file in a gitlab repo (imports that single file)
  • Extract code blocks from a webpage (see code blocks)
  • Otherwise the URL will be considered a raw file (like raw files on github)

If the source URL points to multiple files (e.g github gists and directories), LiveCodes tries to guess which file to load in which code editor (e.g index.html -> markup, my-style.css -> style, app.js -> script). All supported languages can be used. If the source URL points to multiple files of the same category, guessing may not work well. In this case, you may need to provide the files to load and the language for each as querystring parameters. For example:

https://livecodes.io/?pug=page.pug&scss=styles.scss&ts=app.ts#https://github.com/myuser/myrepo/tree/master/mydir

LiveCodes will look for the directory mydir in the github repo myuser/myrepo, and load page.pug in the markup editor, styles.scss in the styles editor, and app.ts in the script editor. The first file in the query string will be shown by default (page.pug in this case).

"Edit in LiveCodes" Bookmarklet

Instead of manually copy/pasting URLs to import, the bookmarklet can be very convenient. It opens LiveCodes in a new window and adds the current webpage URL as a hash. Create a new bookmark in your browser and add this code as its URL:

javascript: (function () {
  window.open('https://livecodes.io/#' + location.href, '_blank');
})();

Importing from CodePen

Currently, CodePen API does not allow directly importing code from pens. However, you can export any saved pen as a Github gist and then import it to LiveCodes. This is even easier if you use the bookmarklet. The format that Codepen exports to gists is well understood by LiveCodes. Most pens can be imported with no or minimal changes.

This is a summary overview of moving code between LiveCodes, CodePen and GitHub gists:

Remember, you can always export your code from LiveCodes as raw source code files, compiled/transpiled code as an HTML file or as project configuration JSON.

Prefill From Code Blocks

Editors can be prefilled by code blocks in web pages. The page is fetched, its HTML is parsed and code is extracted from elements with specific CSS selectors.

Important Note: For this to work, CORS has to be enabled on the target host to allow fetch requests from LiveCodes. This is not required if LiveCodes is hosted on the same host of the target web page.

Add the querystring parameter url with no value, and put the URL of the page with the code blocks as a hash. For example:

https://livecodes.io/?url#https://live-codes.github.io/livecodes-examples/prefill-from-code-blocks.html

By default, LiveCodes looks for elements that match the CSS selector .livecodes [data-lang="${language}"].

for example, in this code block:

<code class="livecodes">
  <pre data-lang="html">
This is identified as &lt;strong&gt;HTML&lt;/strong&gt; code
</pre
  >
</code>

The HTML editor is prefilled with: This is identified as <strong>HTML</strong> code

Notice that the code should be encoded (e.g. angled brackets) to avoid interference with the HTML of the page.

You may wish to specify CSS selectors for elements that contain the code for specific languages. The following example loads the content of the first element that matches the CSS selector h3 as the HTML code:

https://livecodes.io/?url&html=h3#https://live-codes.github.io/livecodes-examples/prefill-from-code-blocks.html

Please note that you may prefill LiveCodes editors embedded in the same page. This works great for documentation websites.

This is a demo for automatic extraction of code blocks to prefill editors by creating "Edit in LiveCodes" links. Also embedded editors are prefilled from the code blocks. (View source)

Prefill Editors by Querystring Parameters

You can prefill the editors by writing content as querystring parameter values, e.g.:

https://livecodes.io/?css=h1{color:blue;}&html=%3Ch1%3EHello%20World%3C/h1%3E

This link preloads the CSS and HTML editors with content and makes the CSS the default editor. This can be convenient to share links with preloaded content without using an external service. However, please be cautious with this method because you quickly reach the ~2000 character limit of URL length. You also need to URI-encode the content (which you can do in JavaScript using the encodeURI and encodeURIComponent methods).

Code Formatting

The popular code formatter, Prettier, is included out-of-the-box in LiveCodes. Code formatting and preview update are triggered by the keyboard shortcut Ctrl + Enter (on Windows) or Cmd + Enter (on Mac).

Tools Pane

The resizeable tools pane provides an area for developer tools. This currently includes the JS/TS console and compiled code viewer. In addition, it shows a loading spinner when the result page is loading. The pane can be resized by dragging the bar. Clicking a tool button toggles opening/closing the pane. Double-click toggles maximize/close.

It can be configured to have any of the following states:

  • closed (default)
  • open
  • full
  • none

e.g. https://livecodes.io/?js&console=open
sets JavaScript as the active editor and opens the console.

JS/TS Console

Console messages are shown in the included console (in the tools pane, below the result page), without having to open the browser console. Message can be sent to the console using the standard console methods in the code editor (e.g. console.log, console.warn, console.error, console.table, ...etc). The console can also be used as REPL (read–eval–print loop) using the included console input.

The code is evaluated in the context of the result page (i.e. variables defined in the script editor are accessible for evaluation in the console input). Also code completion works in the console input. The console input accepts JavaScript and TypeScript code for evaluation.

e.g. https://livecodes.io/?ts&console=full
sets TypeScript as the active editor and shows the console maximized.

View Compiled Code

The resulting compiled/transpiled code can be seen in the compiled code viewer (in the tools pane) in real-time, as you type. This works for all compiled code (e.g. Markdown, Pug, SCSS, Less, Stylus, Typescript, CoffeeScript, ...etc.). This can be a great tool for learning. As you write code, you see the compiled code and the resulting page in the same time. The compiled code viewer shows the code compiled from the currently active editor (markup/style/script). This includes the CSS produced by Autoprefixer (if enabled).

e.g. https://livecodes.io/?ts&compiled=full
sets TypeScript as the active editor and shows compiled code viewer maximized.

This example shows TypeScript code along with the compiled Javascript code, similar to the official TypeScript Playground.

Keyboard Shortcuts

  • Ctrl/Cmd + Enter: Code format + update preview
  • Ctrl/Cmd + N: New project
  • Ctrl/Cmd + S: Save
  • Ctrl/Cmd + Shift + S: Fork (Save as new project)
  • Ctrl/Cmd + P: Monaco editor command palette

These are in addition to the Monaco editor keyboard shortcuts (PDF) that you probably use in VS Code.

Display Modes

The querystring parameter mode can be used to select different display modes. The following display modes are supported:

  • full: This is the default mode with a top toolbar, editor and results panes.

    example: https://livecodes.io/

  • editor: Hides the results pane and works as editor only.

    example: https://livecodes.io/?mode=editor

  • codeblock: A read-only mode just showing only the code block. On mouse-over a copy button appears that allows to copy the code. This is useful when embedded

    example: Demo View source

Embeds

The code editor can be embedded in web pages using iframes. They can still be fully functional and editable unless, for example mode is set to codeblock. Notice they can also prefilled with code, the same way described before.

Examples: Demo - Full Source

<iframe src="https://livecodes.io/"></iframe>

<iframe
  src="https://livecodes.io/#https://gist.github.com/hatemhosny/a0a32216df59e53879b7cd83856cdde4"
></iframe>

<iframe
  src="https://livecodes.io/?mode=codeblock&js=script.jsx#https://gist.github.com/hatemhosny/a0a32216df59e53879b7cd83856cdde4"
></iframe>

This is a demo for embedded editors that are prefilled by code blocks in the HTML of the web page that contains them. (View source)

Intellisense

You can import modules that may not yet be published to NPM and still get intellisense in the editor by providing TypeScript types.

In the configuration file, a modules property allows to map module names to URLs to retrieve from.

Example /livecodes.json:

{
  "title": "My Project",
  "modules": [
    {
      "name": "my-demo-lib",
      "url": "/modules/my-demo-lib/index.js",
      "typesUrl": "/modules/my-demo-lib/types.d.ts"
    }
  ]
}

This allows code like this is the TypeScript editor

Import { Greeter } from 'my-demo-lib';
const greeter = new Greeter();
greeter.morning();

Working demo - Source Repo

If your library implements this code, the code will actually work in the result page, and you get full intellisense and typing support in the editor. This can be of large benefit for library authors in documentation to serve as playground for their code with editor support and can unleash the full potential of such a strong editor like Monaco editor.

Each item in the modules array may contain the following properties:

  • name: The module name
  • url: The URL to the entry point javascript file
  • typesUrl: The URL to the types declaration file.

The url and typesUrl properties should either be absolute URLs or relative to LiveCodes index.html page.

The types declaration file defined by the typesUrl property has to be a single file per module. The module name declared in the file has to match the module name you want to use. The library dts-bundle was found very helpful to prepare such file. (example)

This method can tremendously improve the experience of the developers exploring your code. They do not have to keep revisiting the documentation pages to now the names of the methods or the list of arguments they accept.

You can use this method to get intellisense for your custom modules and also other modules you want. For example you may wish to add the typings for react and lodash.

Security

The result page is rendered in a sandboxed iframe with a unique origin. This prevents embedded editors from having access to the parent page, or to sensitive data like user cookies, localstorage, etc.

API

The documentation for API and configuration specs will be published on a separate documentation website when the API becomes stable. Meanwhile, you can have an idea about the configuration structure by exporting the project JSON.

Roadmap

Many features/fixes are planned, the most important are:

  • Add JavaScript console.
  • Enhancing security
  • Add starter templates (standard and user-defined)
  • CSS presets (e.g. normalize, reset)
  • Improve embedded editors
  • Click to load embeds
  • NPM package
  • View compiled code
  • Offline support (PWA)
  • Github login
  • Export/import from services like google drive/dropbox
  • Support different layouts
  • Small footer with quick tasks
  • Documentation website
  • Add tests
  • Try automatically detecting and loading typescript types
  • Support more languages
  • Improve build process and decrease file size
  • Various bug fixes and performance improvements
  • Improve UX while loading

and may be:

  • browser extension (similar to Web Maker)
  • Support creating exercises with unit test checks

Limitations

  • Client-side only!
  • The Monaco editor is not supported in mobile browsers.

Contribution

Please do!

Feedback, ideas and pull requests are highly appreciated.

Credits

In addition to all the previously mentioned great products, LiveCodes was inspired and initially based on monacode.

License

MIT

Third party packages distributed with LiveCodes and their licences are listed here.

Support the author

Supporting the author allows continued work on open-source software, and keeps livecodes.io free of ads.

ko-fi

livecodes's People

Contributors

hatemhosny avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.