threepointone / ratpack Goto Github PK

ready. set. go!

JavaScript 97.70% HTML 2.30%

ratpack's Introduction

ratpack

[work in progress]

npm install ratpack -g

or download the latest release

ratpack is for beginners, tinkerers, ents, cylons.

quickstart

write a javascript file, say script.js, and save it somewhere. maybe it looks like this -

  require('react-dom').render(
    <div>hello world</div>, 
    document.getElementById('root'))

drag it on to the app, or run ratpack script.js
magic

ratpack gets rid of all the starting boilerplate for building and running the so-called 'modern' javascript stack, letting you immediately jump into the core of your problem.

steals a bunch of code/tools from create-react-app for live reloading, in-browser error messaging, file loaders for css, images, etc, and you can load your own loaders with js pragmas
comes with liberal babel defaults, including future facing extensions (and decorators!). You can also use a local .babelrc file (experimental).
preloads libraries like react, react-router@4, and glamor. It'll also use modules from your own node_modules folder, and you can add your own 'globally' by installing with npm/yarn to ~/.ratpack
use a local public folder to serve static assets that can't be imported (todo - and / or to serve a custom index.html)
use pragmas at the top of your file to configure ratpack
todo - will autoupdate itself whenever I make a 'release', so you're using the latest versions of presets and packaged libs almost as soon they're out
todo - a preferences pane to edit 'global' settings; toggle presets, add libs, etc

long, rambly rationale

tl;dr - old school flow, new age ride.

So, you're reading a tutorial on requestIdleCallback / render callbacks with react / javascript thoughtlording. Or you've just had an idea for a new algorithm for reversing a binary tree. Or maybe you need to write a shitty benchmark to convince your boss that yes, immutable data is fast enough. In any case, you need to quickly write and run some code. What do you do?

These first 2 minutes are critical. The idea you've just had is ephemeral, and needs to be written down fast. It'll be dirty, and you might just throw it away later. At this point, you don't care about the framework wars and modularity shaming and whatever. This is all about you.

Back in my day, I would write a javascript file (and a dumb html holder), and just run it in a browser. Sure, I had a bajillion other problems, but I liked the brutal efficiency of being seconds away from taking a random idea and turning it into pixels. Bikeshedding over 'build systems' was never the first step.

Mind you, we still had build systems, and we bikeshedded a lot over them and how we built our apps, but those 'apps' were a different context; built for teams and stability. Indeed, deep inside those app folders it wasn't uncommon to find 'demo' pages and .md scratchpads for ideas.

But 'personal' coding? Totally different rules. For one, you'd usually want the latest versions of libs. You want as little boilerplate as possible, to jump into the meat of the problem immediately. Maybe you'd have a little /code folder with all your commonly used libs and personal experiments. Even in the context of a larger project, maybe you want to work on a component in isolation, but don't want / need to use the project's main infrastructure.

Times change.

Transpiled languages rose as a way of papering over some javascript's problems, and to use and experiment with future features in browsers that don't support it yet. And it's been absolutely fantastic. The pipeline of new features should keep us busy for a couple of years, if not more. Extensions like JSX and TypeScript make writing code an absolute joy (...well, mostly). I'll be blunt - I can't do UI programming without JSX anymore; having a first class UI construct in your programming language makes soooo much sense. Further, having a React dialect at arm's length means I'm not spending any mindspace on dom mutations. It's the small things, y'know?

The setup process to use transpiled languages though... not so great. You need to install and configure a pipeline of tools, usually cli + node based, in a terminal, and pay this cost almost every time you need to run a new file. nwb, create-react-app, etc get so close, but by nature of their being designed for 'apps', don't achieve the lightweight, experimental feel I'm looking for. Also, CLIs, ick.

We're UI developers. We can do better. By building beginner/tinkerer friendly tooling, we can automate some of our own pain away, and increase how inclusive we are as a community and as a technology. Here's my attempt.

First, some of my 'requirements' -

I'd like to be able to write a javascript file, with es6 and jsx and whatnot, and just run it in a browser. This could be on my desktop, my downloads folder, wherever.
I do not want to have to install or configure anything 'build' related every time.
I'd like some liberal defaults, and include some prepackaged libraries like react, react-router, glamor, polyfills for fetch etc.
maybe I'll have a local node_modules, or in a folder higher up my path
perhaps I'll have a local public folder too, with images and css or whatever I'll need
perchance if I need to, I'd like a custom babel config to mess with a plugin or preset

Let's imagine the core experience - I'd like to have an app (like a legit, macOS/windows/linux desktop app), and I'd like to drag and drop my .js file into it / onto its dock icon, and it would "just work". It could open a browser tab to that file running in a simple html page, and reload whenever I make file changes. A list of previously opened files would be nice.

Hence... drum roll... ratpack. Hope you like it. Lemme know what I could do better, and what you'd like to see!

feature wishlist

better design
frictionless mobile web dev
build / deploy to now / surge / etc
the service worker treatment
end to end encrypted share ala ngrok
multiple languages; flow, reason, node, whatevs
eject config, for carrying on a 'real' project
a smaller package

the shoulders of giants

this couldn't exist without the work of thousands of people in the OSS world. Some projects specifically -

nwb, create-react-app, and the whole family of CLI apps to bootstrap, run and build your javascript apps
webpack2, the giant swiss army knife of javascript bundlers
babel, for all your javascript transformation needs
electron, giving a truly desirable target for building javascript tooling
and of course, react and its entire ecosystem.

project status

This is stil very early work, with a large number of todos to get through before it's 'production ready'. That said, this is already pretty useful. If you'd like to try it out, either try out the prototype mac release, or clone this repo and run npm run && npm run package-app to generate the binary for your computer. Have fun!

ratpack's People

Contributors

Stargazers

Watchers

Forkers

stefanruijsenaars giogonzo orta bradparks ptmt ajeey shubhamgautam thebrokenfinger happy-ferret

ratpack's Issues

Mock API endpoints

https://twitter.com/threepointone/status/819051387040518145

idea: render default export

just an idea.

// @ratpack { render: true }
export default <div>hello world</div>

variant

// @ratpack { render: true }
export default function App(){ // or a class, whatevs 
  return <div>hello world</div>
}

or you could choose a component to render

// @ratpack { render: 'MyComp' }
export class MyComp extends React.Component {
  render() {
    return <div>hello world</div>
  }
}

Decorators?

Using v1.0.6

comes with liberal babel defaults, including future facing extensions (and decorators!)

Got an error:

Uncaught Error: Module build failed: SyntaxError: Decorators are not officially supported yet in 6.x pending a proposal update.
However, if you need to use them you can install the legacy decorators transform

Doesn't work with a custom .babelrc file either.

Works locally

This is what's in my file

function readonly (target, key, descriptor) {
  descriptor.writable = false;
  return descriptor;
}

class Human {
  constructor(name) {
    this.name = name
  }
  @readonly
  speak() {
    console.log('Hi! My name is ' + this.name)
  }
}

const siddharth = new Human('siddharth')
siddharth.speak()            // Hi! My name is siddharth
siddharth.speak = function () {console.log('Hi! My name is dumdum')}
siddharth.speak()

Browserify transforms

It looks like https://github.com/webpack/transform-loader would work fine, which means there maybe just needs to be some means of adding webpack config. Perhaps the nearest config file (package.json? webpack.config.js?) would be the place to hook up this and, more generally, whichever particular tools your project might need.

Error on first launch

I downloaded the release.

I moved the app into Applications folder.

I double clicked it and got the standard security warning that this app is not made from an identified developer.

I went to Settings > Security & Privacy to open the app anyways.

When the app started I got a dialog with the error below. On my 2nd attempt to run the app, it worked fine.

A JavaScript error occurred in the main process

Uncaught Exception:
Error: ENOENT: no such file or directory, mkdir '/Users/me/Library/Application Support/ratpack/extensions'
    at Error (native)
    at Object.fs.mkdirSync (fs.js:922:18)
    at getPath (/Applications/ratpack.app/Contents/Resources/app/node_modules/electron-devtools-installer/dist/utils.js:26:18)
    at Object.<anonymous> (/Applications/ratpack.app/Contents/Resources/app/node_modules/electron-devtools-installer/dist/index.js:42:59)
    at Module._compile (module.js:556:32)
    at Module._extensions..js (module.js:565:10)
    at Object.require.extensions.(anonymous function) [as .js] (/Applications/ratpack.app/Contents/Resources/app/node_modules/babel-register/lib/node.js:152:7)
    at Module.load (module.js:473:32)
    at tryModuleLoad (module.js:432:12)
    at Function.Module._load (module.js:424:3)

File... Open menu

linting

cli support

[edit: simplified]

ratpack isn't trying to do too many things. We'll keep this simple too.

open

ratpack

ratpack path/to/script.js

install app?

ratpack --app

should just open the folder holding the app, that the user can then copy etc

linux

similar to #25, but for linux.

reasonml

Install packages when it sees new require

E.g. writing quick bit of code and you realize you want lodash and ratpack installs that in the background for you.

Probably can just use https://github.com/ericclemmons/npm-install-webpack-plugin

pragmas

refs doesn't bind correctly, componentDidMount

Nice idea 👍 to use electron.
I have problems with refs - refs does not initialize correctly.
Also, componentDidMount lifecycle seems to have problems

Ratpack?

Hi!

Looks like your name & color choice is... errr.... a bit conflicting with some popular project in JVM world:
https://github.com/ratpack/ratpack

editor integration

Option to run relative to directory

Drag and drop is nice, but perhaps there's a way of running this from the command line or relative to a given directory? Perhaps the window would list js files in that directory? Perhaps drag-and-dropping a folder lists all the js files in it? The ability to quickly switch between files with common setup would be awesome.

I usually use budo, which is great; it's just the lack of multiple entry points that's the main hangup (ref: mattdesl/budo#139 ). I've been meaning to invest a bit of time to better understand and improve my setup; it's just never quite worthwhile.

stale webpack options

there's a bug where the server seems to be serving with a compiler from a previous instance when you change pragmas. this is similar to the issue I had with webpack using the same port (hence the hashing / port number genration). should solve this properly.

logs

should dump logs somewhere so can gather them for errors, etc

pragmas

magic pragmas

ratpack supports some magic incantations you can put at the top of your entry file
to customize the webpack/babel backends. A simple example would look like this -

/* @ratpack {
  devtool: 'eval',
  alias: {
    react: 'preact-compat',
    react-dom: 'preact-compat'
  }
}
*/
require('react-dom').render(<div>look, preact!</div>, window.root)

(assuming preact-compat is available locally or in ~/.ratpack/node_modules)

Here's a full list of 'somewhat working' pragmas

devtool

devtool: 'source-map' (ref.)

public

public: './my/public/folder' (ref.)

jsx

jsx: 'Inferno.createElement'

This is different from babel's @jsx pragma, in that it will apply to all js files, not just the one

proxy

proxy: { '/api': 'http://localhost:3000' } (ref.)

provide

provide: { 'Glamor': 'glamor/react' } (ref.)

alias

alias: {
  react: 'preact-compat',
  react-dom: 'preact-compat'
}

(ref.)

define

define: { 'process.env.NODE_ENV': 'test' } (ref.)

rules

rules: [ { files: '*.vue', loader: 'vue-loader', options: { some: 'options' } } , ...]

nb: files is a glob, which gets converted to a regex for webpack's test prop

babel presets and plugins

babel: {
  presets: ['vue', [ 'a11y', {...} ],
  plugins: ['./some/path', ... ]
}

These don't 'work' yet, but sharing possible syntax

target

target: 'node' (ref.)

offline

offline: <options> (ref.)

autoinstall

autoinstall: true (ref.)

plugins

plugins: [ {<module> <options>}, ... ]

other

reload: true
hot: true
production: true
port: 3999

thoughts/questions/ideas?

autoupdate

This is a lot more intense that I could imagine. It involves -

compile code, not using the babel-register hack
integrated with autoupdater
use electron-builder to generate installers for each platform
that also involves getting code signing certificates($$$!) per platform
probably have to set up CI on travis + appveyor to get builds for all platforms
deploy a nuts server (to now.sh?), making sure not to proxy requests to github
figure out a schedule by which I can regularly replease on npm, but do slower auto update releases (so as to not kill user's bandwidth) and yet allow them to optionally update of required

brrrr.

so it appears this is a long term goal. To shorten the pain, we'll get cli support in (#11), and write docs showing how to install / run from cli. this has advantage of updates always being small, but disadvantage that they have to do it by hand. We'll see what we can do to make that painless too.

windows

this is a catchall issue for windows bugs/quirks. @shrayasr, calling on your help for this.
there are 2 major touchpoints to make sure this thing works for windows. bin/ratpack, and src/app.js. further, I've marked possible areas to check with //todo - windows specifically stuff to do with paths. a lot of it should 'work', but who knows :P

your mission, if you choose to accept it, is to make this work on windows :)

hmr

what's the story with hmr with react? what about vue et al?

Pragma rules fail when query params present

Is it possible that ratpack isn't handling query parameters in loader names correctly? I'm not all that familiar with webpack and am having some trouble setting up a loader. The obvious fix just passes the problem elsewhere so that I'm not quite sure how to fix it.

My ./ratpack/package.json looks like this:

{
  "name": "ratpack-local",
  "dependencies": {
    "brfs": "^1.4.3",
    "transform-loader": "^0.2.3"
  }
}

My test.js looks like this

/* @ratpack {
  rules: [{
    files: '*.js',
    loader: "transform-loader?brfs",
    enforce: "post"
  }]
} */

I get the following error in the ratpack console:

If I remove ?brfs from the loader name, then the module lookup seems to succeed, except now I get this in the browser console:

I hate to put this on you (everything else is looking great!) but just wanted to check run by you the possibility that it might be a corner case in how ratpack is handling this. 🚀

build / deploy

2 separate things

build - make a production build, with h2 friendly assets, etc ready to go
deploy - push to surge and / or now.sh

// @ratpack { target: 'node' }
console.log('we in node yet?')

experience - instead of opening a terminal, we could setup remote debugging and open up a browser tab instead, with the chrome dev tools loaded etc.

how to 'restart' the app? cmd+r? a button?

buttonbar

edit/build/deploy/share
~