WIP: Quality, Tools and Packaging

[konsumer]

This is a WIP, and should not be merged until these are complete:

• demo seems broken, need to test more
• no jQuery (ES6 over jQuery #5)

I am working on these now, and will remove this header and the WIP from title once it's ready.

In this PR

This is a big code-quality & tooling PR that normalizes the code, removes jquery dep, adds tools for publishing & developing, and should close the non-question issues, once it's setup. Normally, it would be wise to break so many changes up into a bunch of PRs, but everything sort of depends on each other or made it much easier to make the fix, and I wanted to get it all working right at once, so I just put it all together.

If any of this seems annoying, hard, unclear, wierd, or superfluous, I'm happy to chat in more detail about how it works, how to use it, or explain the reasoning behind the particularr change, as well as make changes to how it all fits together. Overall, it should make everyone's life easier, and the net-goal is higher quality code with less work.

• package.json for publish (Publish to npm #10): You should do npm version patch && npm publish
• basic .gitignore & .npmignore for node development
• Package stuff for use as a library - files export stuff correctly, setup for unpkg, es6 modules, and old es5 commonjs builds
• formatting standard: lint tools & a few manual fixes. This may not be the format you want to use, but this is my fave. airbnb is also popular, and we can easily switch. It will make your life much easier to install a linter for your editor that fixes everything when you break the rules. I use sublimelinter + standard, but there are a ton of presets & plugins for various standards & editors. It also helps contributors keep the code consistant.
• build-system: files from src/ get built into docs/ & dist/ in various formats for publish, build-process is now in code
• gh-pages: docs/ can be set as the demo page on gihub, for automatic github-pages support
• Basic unit-test support with jest
• moved template strings out of code in demo, so it's easier to read & reason about
• use maps instead of if/else to simplify template-switching
• beutify & normalize quotes on all the demo template-strings so they are easier to read & work with in code

Commands

npm i           # install development tools
npm start       # run hot-reloading demo on local, for dev
npm test        # run unit-tests
npm publish     # build & publish to npm (do `npm version` first to update version in package.json & git-tag)
npm run lint    # check & fix code-format
npm run build   # just build library & demo (for gh-pages or whatever)

TODO

These need some discussion or work outside of this PR:

• Come up with another npm-name for project, so we can publish (flowy is taken) maybe flowy-editor?
• Actually publish to npm. I leave this to you, but should be as simple as npm version patch && npm publish
• Document all these features in README. I can help with this, if you like all these changes
• More unit-tests. I just added basic support to show how it works
• Travis CI or similar - up-to-date testing, automatic build & publish to npm
• Badges for code-quality, CI status, etc
• Code of Conduct & contribution guide - good if you want other people to work on things
• Move demo to gh-pages branch. I like this better than docs sub-dir, and it makes it so the repo isn't cluttered with generated files, on master
• Wrappers for react & vue (as seperate projects.) I want to use it in react, so I'd be happy to make that one.

[DanielRuf]

Could we need some CI setup?

[konsumer]

Yeh, it's in the TODO at the end of description.

[joelvh]

@konsumer is this still a work in progress? I'm interested in using this in react and trying to determine if I'd be duplicating work.

[joelvh]

@konsumer P.S. I would start with making this an NPM module with a build process first

[konsumer]

@joelvh I got busy with other work. Feel free to use any ideas you find here. I ended up having issues with the demo not building, I think I probably left some key thing out.

[joelvh]

@konsumer i got #37 and #38 going. Thanks for the help!

[konsumer]

@konsumer P.S. I would start with making this an NPM module with a build process first

This does have build process. (see npm run build.) for npm, I would do this:

"prepublishOnly": "npm run build"

but otherwise it should be all ready for npm, once the demo works.

[joelvh]

@konsumer yeah, i took some of your build tools - have a working demo too. It's all in #37. Major refactor in #38 and React implementation in #39

[taf2]

Would love to ensure we preserve the simplicity of this project to avoid needing to compile code to run it. Part of the usefulness in this project is that it has no build dependencies

[konsumer]

Would love to ensure we preserve the simplicity of this project to avoid needing to compile code to run it. Part of the usefulness in this project is that it has no build dependencies

The build is optional, and just for publishing on npm. Using ES6 has become a pretty standard way to distribute a JS library for the web and elsewhere.

If you look here, it just injects a global in the window (flowy) without exporting it, so no build system will really work with that. It relies on the default scope in ES5 browser js being window but JS doesn't always work that way. Another way that works today, is to use web ES6 modules:

<script type="module">
import flowy from 'https://path.to.cdn/flowy.js'

// do stuff
</script>

If the code is structured as an ES6 module, additionally, it can be used in any modern build system, as well as no build system.

Another option would be to add a trivial import entry-point that does the same thing:

// flowy-global.js
import flowy from './flowy.js'
window.flowy = flowy

<script type="module" src="'https://path.to.cdn/flowy-global.js"></script>
<script>
// use flowy exactly as you did before, even though I wouldn't really recommend this
</script>