> Then you can just nix-env -iA your-package.

This is what always gets me stuck. It seems like lots of tutorials assume you're installing packages by hand still. For me, the whole reason I'm using nix is so that I can use the declarative package management.

I get having local dev dependencies on a per-project basis and running a nix shell to make those dependencies available in your development environment.

But it's just confusing to me how many tutorials suggest running nix-env -i to imperatively install a package. Why would I do that instead of taking advantage of the joys of declarative package management?

Because Nix is a language there are many ways of accomplishing the same thing. Some ways are easier, some require more work. For example if you make a derivation in your home, it is easy to install it with nix-env from there, and you are done, but if you want to include it in your configuration, you typically would create an overlay that includes your package in nixpkgs. Then you can list the package. If your derivation requires creating a configuration, service etc. On top of that you will also need to create module that specifies configuration options and configures the application.

So in many cases you are told to use nix-env, because the person just answered how to write a derivation and didn't go further than that.

I think flakes (still work in progress), will help here, because it defines a standard that supposed to do all of that in one file that is easily composable.

I've never used nix-env on NixOS. I really think that command only exists as a bridge for people used to more traditional OS's. I think there is a space for it - if you don't want to spend time building your user configuration declaratively, just install what you need and get going.