Skip to content
master
Switch branches/tags
Code

generator-django-rest npm Build Status GitHub license Updates

A Yeoman generator for easily bootstrapping a Django REST API with some common settings and quickly deployable to Heroku/Dokku. Check out this quick screencast showing you how to deploy a full-fledged Django REST API to Heroku in 5 minutes:

asciicast

The goal is to keep you efficient and include features you need in a typical modern web app, yet keeps things simple and not too bloated. You can see an example generated Django project here. For some background on how and why the project was created, read this article.

Note: the project is still considered to be in beta until I get a chance to test it on more apps. That said, I am using it in my own projects :)

Features

Some of the cool features that come with generator-django-rest are:

  • 🚀 quick to launch – start a new project and deploy it to Heroku in 3 commands:

    yo django-rest
    ./scripts/install.sh
    ./scripts/deploy.sh
  • ⚡️ productive – start the Django, DB & optionally frontend dev servers easily

    ./scripts/start.sh
  • 🐳 Docker support – get a complete environment with Django, Postgres & Redis in a single command:

    docker-compose up
  • 🦄 modern JS – serve static files on / using django-spa for nice single-page apps using React / Angular / Vue…

  • ⚛️ GraphQL – interactive API with filtering and nested queries using Graphene

  • ⛵️ monorepo - option to automatically set up a create-react-app frontend for you in the same git repo with everything integrated under the mantra one app, one repo, one dyno

  • 📦 Heroku-friendly packaging – if you're using the built-in React frontend, deploy.sh minifies the frontend and packages it up with Django into a separate prod branch ready for deployment as a Django web app (that gets deployed to Heroku by default)

  • 🍣 Dokku support – quick to deploy to Dokku, a DIY alternative to Heroku

  • 🤓 12-factor config – environment variable configuration using django-environ

    • define a variable in .env for dev e.g. REDIS_URL=redis://localhost:6379/0
    • use it in settings.py, e.g. CELERY_RESULT_BACKEND = env('REDIS_URL')
    • set variables on the prod server (just works™ with Redis on Heroku)
  • 🔋 batteries included

    • Celery with a Redis backend – cause you'll need an async task queue
    • Backblaze B2 media file storage backend (optional)
  • 📜 sane logging – defaults to fail nicely

  • 🐶 familiar – check out the rough project file layout, it's much like django-admin startproject myproject would set it up (only repeats the project name twice, i.e. ~/code/myproject/myproject/settigns.py). An example generated app is published as metakermit/hellodjango.

See CHANGELOG.md for a full release history with all the features.

Getting Started

To begin, you need to install node.js. Once you have that, you need Yeoman pre-installed. Yeoman lives in the npm package repository. You only have to ask for him once, then he packs up and moves into your hard drive.

npm install -g yo

Then, we need the django-rest generator, i.e. plug-in. You install generator-django-rest from npm.

npm install -g generator-django-rest

Finally, for every new project you would initiate the generator in an empty folder.

mkdir myproject
cd myproject
yo django-rest

Now check the HACKING.md file in the generated code project for extra instructions (generated from this template if you're curious).

Contributing

If you have some ideas for contributions, suggestions are always welcome. Note, however, that the goal of the project is to stay minimalist, so we'll try to keep the number of dependencies small.

As a reminder to myself, I release a new version of generator-django-rest by running:

npm run release:patch # or :minor or :major
npm publish

License

MIT