Src/declarations in repo or not

Developers
1

Do you commit the src/declarations folder and content of your dapp in your repo?

I always do so but, notice that the dfx starter kit doesn’t and adds the folder to the list of .gitignore patterns. So curious to know what’s the common practice here.

1 Like
2

The reasoning I always hear is that automatically generated stuff should most likely not be committed since it can be reconstructed trivially

3

I share the reasoning but it is not always applied in practice. e.g. in Capacitor projects it’s a best practice to commit the autogenerated files, this mostly for maintainability reason. That’s why I am curious to gather some feedback of dapp devs.

But you are for sure right, I might be the only one that does so currently.

4

I commit them because sometimes I put declarations from other projects in there as well.

1 Like
5

That’s a good point

In addition, I personally commit the declarations for:

  • maintanability reason because it is sometimes handy to just check if anything as changed in the declarations

  • generating proper declarations for my code need some more steps - like formatting with prettier and duplicating the js files to mjs so that I can run these in NodeJs scripts. Likewise commiting declarations guarantee that these steps are in sync

  • it’s also a way to make the did files public

  • finally it’s kind of easier for the community to checkout and try out my dapps if the declaration are already there - i.e. only the backend needs to be deployed and the dapps can be run as it

But again, that’s maybe just me and why I started this thread.

1 Like
6

Also very valid points and I agree on them

1 Like
7

I’m also pro committing the declarations, and I agree with @peterparker 's reasons above

2 Likes
8

These are all good points. I want to provide some reasons for not committing the declarations:

  • To avoid the confusion that you can edit the files in declarations. With the default setting, dfx build or npm run build will always overwrite everything inside declarations. If you change some files there, it silently gets overwritten. This feature can be disabled by editing packages.json, but it can be hard for beginners to find out.
  • If you want to commit the declarations directory for read-only purposes, you can always do so by updating the .gitignore file. The intention for not committing declarations in dfx new template was to avoid the confusion above.
9

Should we add a comment in each file?

/**
 * WARNING: Do not edit - this file is generated automatically by dfx
**/

I get your point @chenyan, these are reasonable thoughts but, as I said above, from a practical point of view, I think personally that they should not be excluded per default.

Anyhow, I opened a discussion / feature request. Does think it’s a good idea, welcome to upvote. Does think it’s a bad idea, welcome to downvote.

:point_right: https://github.com/dfinity/sdk/discussions/2764

10

I am also hesitated to add the Do not edit warning, as we do expect some projects to edit the files there, especially index.js to control how you want to setup the agent. You can disable the overwriting by editing packages.json.

I think the question here is that in the default setting, should we include declarations or not. There are arguments for both directions, and users can always choose to go a different route than the default setup. As a starting point, maybe a good documentation can already help?

1 Like
11

Makes sense.

Not sure, sounds more like something that the code explains itself.

Anyhow, that was just my practical two cents.