/popcode

An HTML/CSS/JavaScript editor for use in the classroom

Primary LanguageJavaScriptMIT LicenseMIT

Popcode

Popcode is a simple HTML/CSS/JavaScript editing environment for use in the classroom. It's a lot like JSBin, JSFiddle, or CodePen, but it focuses on giving specific, immediate, human-friendly feedback when the code contains errors.

Project status

Build Status Dependency Status License

Popcode is the official editing environment for the Code Nation Intro to Web Development program in the 2019–2020 school year.

Try it out

You can try out Popcode at https://popcode.org.

Table of Contents

Features

  • Edit HTML, CSS, and JavaScript in the browser; in-browser preview updates as you type.
  • Get immediate, comprehensive, easy-to-understand feedback about problems in your code.
  • Errors can't be ignored. If there are any errors in the code, the live preview is replaced by an error list.
  • JavaScript runtime errors are also reported in human-friendly language, with annotations in the source code pointing out the source of the problem.
  • One-click login using GitHub account; all work is saved remotely to Firebase when logged in.
  • Pop out preview of web page in its own window.
  • Export to GitHub gist.
  • Import starter code from a GitHub gist.

About validation

The validation system is the main point of this project. Most syntax checkers, linters, and style enforcers tend to provide feedback using language that is geared toward experienced coders, not beginners. Thus, providing a translation of error messages into plain English for students is the overriding concern of this project.

Popcode tends toward strict enforcement of lint and code style, even when enforced style decisions are arbitrary, under the philosophy that giving students one right way to do it eliminates ambiguity and aids the learning process.

Technical details

Popcode uses React to render views, Redux to manage application state, Ace as the code editor, Webpack to package the client-side application, and Babel to compile modern JavaScript for compatibility with legacy browser versions.

Popcode detects mistakes in student code using slowparse, htmllint, HTML Inspector, Rework CSS, PrettyCSS, stylelint, jshint, and esprima.

Contributing

Yes please! Pull requests, bug reports, and feature suggestions are all very very welcome. When you’re first getting started, I recommend picking a good first issue so you can get your feet wet and make sure you can run a development environment smoothly.

Everyone is welcome to submit a pull request that implements a new feature or fixes a bug that you’re particularly passionate about. But if you just want to help out and you’re looking for ideas, your best bet is to browse issues with the help wanted label.

Local development environment

Popcode comes with a batteries-included development environment built on nodeenv. You will need to have Python installed; any version 2.7+ will work. To set up the environment, run:

$ tools/setup.py

This will install node and yarn in an isolated environment in the nodeenv directory of the project root. It won’t interfere with any system-wide installation of those tools.

Once setup is complete, to run a development server, run:

$ tools/yarn.py start

This will start a server on http://localhost:3000

To start Jest tests in watch mode, run:

$ tools/yarn.py autotest.jest

To start Karma tests in watch mode, run:

$ tools/yarn.py autotest.karma

Check the "scripts" section of package.json for other useful tools.

Developing in VS Code

Popcode comes with a robust custom VS Code configuration, which is automatically enabled by tools/setup.py. If you use VS Code, you can:

  • Run the Show Recommended Extensions command to easily install extensions that improve the Popcode developer experience
  • Start a server, run tests, and more by typing task into the Quick Open bar to autocomplete the task to run
  • Debug either your development environment or a Jest test by typing debug into the Quick Open bar

Using other editors

Popcode uses tools like Prettier, ESLint, and Stylelint to automatically format code. We recomment setting up editor plugins to auto-format on save; alternatively, you can run tools/yarn.py lintfix before committing to format and autofix lint. Popcode’s official VS Code integration (with recommended extensions installed) does this out of the box.

Alternative development environments (advanced)

There is no requirement that you use the official development environment to work on Popcode; you’ll mostly just need the right versions of Node and Yarn installed on your machine (check the "engines" section of package.json for the current versions).

Developer Reference

Popcode endeavors to use up-to-date technologies and code conventions to make development as pleasant as possible. Below are links to reference documentation on the major tools:

License

Popcode is distributed under the MIT license. See the attached LICENSE file for all the sordid details.

Contributors

Thanks to

These companies generously offer Popcode access to paid tiers of their excellent services, free of charge:

BrowserStack Bugsnag

Contact

Feel free to email me at mat.a.brown@gmail.com if you have any questions.

You can find our Slack team, including our #dev channel, here.