Would an example folder be welcome?

[woile]

Hi everyone, thanks for this awesome project. It does feel more intuitive and simpler to use than flake-utils, and I'm quite happy with it. But I'm struggling with the lack of examples. It took me a while to find how to use devShells, and I haven't seen much examples around (I'm relatively new to nix).

My goal would be to see at least one example for each different output supported by flake-parts. I could start sending a PR for the devShells example, and I was thinking it would be nice if we have examples for:

• running commands (for example a set of commands: build, deploy)
• configuring formatter (is it something to run things like black or rust fmt? I cannot tell from the docs)
• apps (what are these for?)
• checks (what are these for?)
• nixosModules (I see one example for nixosConfigurations, but not for modules)

btw, I hope the above is correct, it's what I see when I run nix flake show 😅

[roberth]

Hi @woile,

Yes, examples (and/or documentation in general) are very welcome!

I think a good start would be just to do a editing pass over the option docs, but if you prefer to create complete examples, that's also great.

Likely we can improve the infrastructure around examples, templates and tests; so contributions in that area are also welcomed, but not a prerequisite for contributing examples.

• configuring formatter (is it something to run things like black or rust fmt? I cannot tell from the docs)

According to upstream docs, it's meant for formatting .nix files, but that may be unenforced.

I hope the above is correct

Those are definitely some of the outputs! I think formatter is a bit of a weird one, and for the other ones, the existing option docs could be a starting point.

There's probably more to discuss, like possible tooling improvements or what to do about other projects' examples, but I think I've answered your questions so far and I don't want to bore you ;)

I could start sending a PR for the devShells example

I think that's a great start. Not sure if we need to discuss a lot so it's good to have a starting point and work from there.

[srid]

I'd also suggest dedicating a page or section linking to real-world examples. Here's one:

• https://github.com/nix-community/nixd/blob/main/flake.nix

[woile]

I created a first PR, let me know what you think 👍🏻

I like the examples folder because they are great isolated-working examples that just work. In my experience when using rust, the examples folder have been tremendously helpful, and I think it would really help nix get a wider adoption.

We could also use this issue to collect snippets if you want.

More examples with workflows described I'd like to see:

• [ ] secret management
• [x] makefile replacement
• [x] replacement to Scripts to Rule Them All
• [ ] python example
• [ ] typescript example
• [ ] monorepo example
• [ ] loading .env files in a devshell or a package
• [ ] home-manager example
• [ ] mac manager example