These guidelines have been authored with the following things in mind:
consistency All code should be formatted and written the same way
maintainability Having automated tests to check the main functionality of the application allows us to keep apps up-to-date
pluggability By keeping a consistent application format and a minimum consistent set of dependencies means developer can more easily combine different applications
contribution-friendliness Every template/application should be friendly to new contirbutors to allow to fix bugs or add missing features.
With these criteria in mind we came up with the following guidelines. These guidelines have also been used to create the following repository templates that you can use to bootstrap your project:
Any of our applications should feel familiar to the developer. While for a general Node.js application that might mean we can start with a blank slate application, for some applications like a React app this means starting with the standard bootstrapped project. For example using create-react-app for React, ng init for Angular, etc.
After that see how the remaining guidelines fit into this.
Linting allows us to keep the code consistent. The rules themselves are less important than the actual presence of a linter as long as there's the capaibility to "auto fix" or proper guides that make it easy for new developers to adhere to the linter rules.
Our code should be reliable and maintainable and testing plays a big part in this. The more tests you can author for your application, the better. However, at the very least you should have some general tests covering the core functionality of your application. This will allow us to keep applications easier up-to-date with automated dependency updates.
When in doubt you should cover tests for template applications in the following order:
- Test the endpoints/webhooks your app is exposing
- Create E2E tests for your user interface to check for the basic functionality
- Write additional unit tests starting with the mosts complex/critical functions
In general you should use as many or little libraries as it makes sense for the respective target audience. Less libraries and dependencies makes it easier for people to adopt it. But if that means the codebase increases significantly because of code that is seemingly unrelated to the use-case, use a library/dependency instead.
If an application can be written in a serverless & stateless fashion like using Twilio Functions, you should prefer that, write your template as a Function Template and submit it to github.com/twilio-labs/function-templates.
Credentials for Twilio and other external services as well as things like service SIDs should be stored as environment variables. In order to make it easy for people to get started, every project should use .env files for this.
The actual .env file should never be included in a template and should be part of the .gitignore file. However, a project should have an .env.example file that specifies every environment variable necessary, including default values where applicable and a comment line (prefixed with #) above it specifying what this value is and how to retrieve the value (for example sign up at twilio.com).
The tool configure-env can be used in a setup script or in the setup instructions and will use the .env.example file as a fundation to prompt the user for these values
Most programming languages offer libraries that help working with .env files.
We want to make the project setup for people as easy as possible. In order to avoid them having to wrestle with databases, whenever possible, you should use a filesystem based one. One database that works with a variety of programming languages is SQLite3
If possible you should also pre-populate the database with some basic data.
GitHub introduced GitHub Actions as a way to run continous integration tests directly on their platform allowing to test apps on Windows, Linux and macOS. This is our preferred way of running tests and other automation. You can find some basic templates in the sample repository: https://github.com/twilio-labs/sample-template-nodejs/tree/master/.github/workflows
Every project should have the following files to improve the experience for developers:
README.mdwith a structure following the template projectCONTRIBUTING.mdexplaining how to contribute to this project for example to fix bugs. This can be included in theREADME.md
As for the overall structure of your project, follow what's the best practice for the target audience.
For a general applications, take a look at the available templates listed further up.
In addition to the general guidelines we also started creating language specific guidelines:
Can't find your programming language? We are slowly adding more programming languages to the guidelines. If you'd like to contribute, feel free to create an issue and let us know how you'd like to contribute.