SurviveJS – Maintenance

Availability

Although you can read the book online for free, you can also purchase it in a copy to support the development of the content. See also consulting for other available options.

• Leanpub (digital, always up to date with the site)↗

Table of contents

1. Preface Once an initial version of software has been developed, it often becomes the subject of maintenance efforts. You will have to evolve the code to match new requirements. Doing this is challenging when technology keeps changing. Especially web development is prone to this as the stack and standards k…
2. Introduction The popularity of JavaScript and related technologies has exploded. As a result there are now numerous open source projects which rely on the language. JavaScript is widely used for web development and it sees further use beyond the web. The popularity and on-going evolution of the web platform pos…
3. Packaging In this part, you’ll learn how to package your projects for consumption through npm. You will also learn to manage releases, generate standalone builds, and manage dependencies. …
4. Where to Start Packaging npm has become wildly popular for managing JavaScript packages. It started in the backend world but has since grown to include frontend libraries as well. And now we have another issue: it’s hard to find a package your need because there are so many, and you end up creating a new one increasing the…
5. Anatomy of a Package A minimal npm package should contain metadata in a package.json file and an associated source file (usually index.js). In practice, packages contain more than that and you will have at least a license file and the source in various formats. Often projects contain more files than are required to ex…
6. Publishing Packages Publishing npm packages is only a npm publish away. Assuming the package name is still available and everything goes fine, you should have something out there! After this, you can install your package through npm install or npm i. Most of the community follows a specific versioning convention whic…
7. Building Packages While publishing packages, you have a few concerns to worry about: Which browsers and Node versions to support? What to do if we want to use language features that aren’t supported by these targets? What to do if we want to use another language than JavaScript to author our package? How to support…
8. Standalone Builds The scenarios covered in the previous chapter are enough if you consume packages through npm. There may be users that prefer pre-built standalone builds or bundles instead. This comes with a several advantages: Everything is packaged into a single file. You can include the bundle using a `` tag. T…
9. Managing Dependencies Keeping dependencies updated is important to have the latest bugfixes and security updates, but it needs a lot of work: once in a while you need to check which packages have new versions and how to migrate, sometimes you have to rewrite parts of your code. Bigger projects may provide codemods that …
10. Code Quality In this part, you’ll learn about different aspects of code quality. You can use the ideas to evaluate other people’s projects and to improve the quality of your own. …
11. Linting We read code more often then we write it: sometimes we spend hours looking for what caused the bug, only to fix it with a single line of code. That’s why consistent code style is important. Ideally code in a project should look like it was written by a single developer. It makes code easier to read…
12. Code Formatting Usually linters can validate and fix code formatting but there are specialized tools that work better. Achieving Code Consistency Code consistency helps when several people work on the same codebase: code look similar everywhere; programming patterns used consistently across the codebase; naming…
13. Typing A function interface is a contract and depending on the system, it gives you guarantees. JavaScript doesn’t give any guarantees by default and you can pass anything to a function. Doing this may lead to a runtime error and crash your application. In a stricter system it’s difficult, or even impossi…
14. Testing Tests can be seen as a runnable documentation of your code. Automated testing gives you confidence to change the code. Manual testing is the other end of the spectrum. It’s also the most labor intensive and brittle option. What to Verify With Testing Testing can be used to verify at least the fol…
15. Infrastructure In this part, you’ll learn how to set up an infrastructure to support your project. By doing this well, you’ll make it easier for others to contribute to your project and make it grow faster. A good infrastructure becomes particular important as a project grows. …
16. Processes Each project has processes around it. Services like GitHub, GitLab, and Bitbucket provide plenty of tool to manage open source projects: version control for project source, issue tracker, pull requests to accept code from your users, and often hosting your project site. When you think about proces…
17. Continuous Integration Continuous integration (CI) services will run your tests in several environments: different operating systems, browsers or Node versions. It’s would be complicated to setup on your local machine. Usually CI checks every commit to your master or development branch as well as on each pull request — C…
18. Automation Everything that can be done by a machine, will eventually be done by a machine. One of the earliest "computers", the Jacquard machine, achieved this for manufacturing complex textiles. It displaced human effort this way and pushed the difficult and monotonous task to a machine. This is the whole po…
19. Documentation In this part, you’ll learn how to write a good README and a good change log, how to generate documentation for your API and create a site for your project, and about other kind of documentation that may help your users. …
20. README A project README is often the first thing people see when they find the project. The project’s site is another entry point. Often a site is generated from a README file content with nice CSS. A good README can “sell” the project to a potential user. A badly written or formatted one can scare users…
21. Change Logs Change log is an essential part of an open source project: it tells the user what was changed in a new version, about new features and breaking changes, and how to migrate to a new version. Why Not Commit Log Many projects don’t have change logs and ask users to read the commit log. But commit lo…
22. Site Project site isn’t only a marketing tool — it also allows you to show your project to its potential users and give them the opportunity to try the project in their browsers. For many projects GitHub repository would be enough but Markdown pages are the only tool you have there, and a site have som…
23. API Documentation For small project you can write API documentation manually in the README file, but for larger projects it’d be hard to maintain. You will need to generate API documentation from the code. Documenting APIs in Code JavaScript The most popular format for documenting JavaScript APIs is JSDoc. It use…
24. Other Types of Documentation Contribution Guidelines Contribution guidelines explains how to contribute to a project: how to setup the environment; code style; what kind of contributions you want; links to all relevant documentation. GitHub will show a link to contributing guidelines on the new pull request page. Read more…
25. Linting and Formatting Text linting is much less common than code linting, but if you have to maintain a lot of text it may save you a lot of time, and improve quality of your documentation. Linting Markdown With Textlint and Proselint Text linting is less common than code linting but in large projects with many contri…
26. Future In this part, you’ll learn how too consider the longevity of your project and how to market it if popularity is one of the goals of it. …
27. Longevity When developing a project, you should consider its goals and timespan. Some projects are one-off and meant to solve an immediate problem and are then thrown away. Others have more longer term focus and evolve over a long time. The question is, how to enable this long term evolution? You have to co…
28. Marketing Even the technically most excellent project in the world won’t have much impact unless it reaches potential users. Popularity isn’t a goal always, but if it’s, then it’s good to know how to approach marketing the project. The purpose of marketing is to connect the potential user with the project. …
29. Appendices TODO …
30. Managing Packages Using a Monorepo npm packages can be managed in multiple ways. The most common way is to have one package per a source repository. The problems begin when you have to orchestrate changes across multiple related packages. The idea of monorepos was designed for this purpose. Monorepos - What Are They A monorepo all…
31. Customizing ESLint Even though you can get far with vanilla ESLint, there are certain techniques you should know. For instance, sometimes you want to skip specific rules per file. You can even implement rules of your own. Speeding up ESLint Execution One of the most convenient ways to speed up ESLint execution on b…