Proposed Directory Structure Changes in CFWheels 3.0

[bpamiri]

Hi everyone,

I wanted to open a discussion and get the community's input on a proposed directory structure change in CFWheels 3.0. We are working towards a 3.0 release candidate release in the next week or so and a couple of the features that have already been integrated into the bleeding edge branch are the capability to reorganize or move the application code and wheels directories with a configuration change. This feature was integrated into the framework as a direct result of a request from the community for the ability to move the wheels directory or the application code out of the root of the website.

Alas, one of the mantras of our framework is convention over configuration, so it doesn't seem right to add the capability to modify the directory structure and not actually change the directory structure if most users will want that directory structure to be changed. I'm getting myself all twisted in the words, basically what I'm trying to say is this, now that this capability has been added to the framework, should we entertain the idea of reorganizing the default directory structure of the framework to better align with other modern frameworks and even modern Ruby on Rails itself.

Currently a CFWheels application has the following directory structure:

webroot
├── config
│   ├── development
│   ├── maintenance
│   ├── production
│   └── testing
├── controllers
├── events
├── files
├── global
├── images
├── javascripts
├── miscellaneous
├── models
├── plugins
├── stylesheets
├── tests
├── views
└── wheels

What I'm proposing as the default new directory structure is this:

webroot
├── app
│   ├── config
│   │   ├── development
│   │   ├── maintenance
│   │   ├── production
│   │   └── testing
│   ├── controllers
│   ├── events
│   ├── global
│   ├── migrator
│   ├── models
│   ├── plugins
│   ├── tests
│   └── views
├── files
├── images
├── javascripts
├── miscellaneous
├── stylesheets
└── vendor
    └── wheels

As indicated above, the app and the vendor directories can be moved completely out of the webroot and there are times when this is the desired solution, but the proposed structure aligns better with modern application design, I think.

I would love to hear your input on this proposed change as well as your thoughts weather the config directory should be in the webroot as Ruby on Rails has it or in the app directory as indicated in the proposed directory structure above.

-Peter

[neokoenig]

I would actually consider going one step further;

repo root
├── app
│   ├── config
│   │   ├── development
│   │   ├── maintenance
│   │   ├── production
│   │   └── testing
│   ├── controllers
│   ├── events
│   ├── global
│   ├── migrator
│   ├── models
│   ├── plugins
│   ├── tests
│   └── views
|── web <---- web root
│   ├── assets
|   |   ├── files
|   |   ├── images
|   |   ├── javascripts
|   |   ├── miscellaneous
|   |   ├── stylesheets
└── vendor
    └── wheels

This way configuration files such as package.json / box.json / node_modules etc won't get accidentally deployed to the webroot;

app = Your CFML
web = Public Web Root
vendor = Other CFML.

But I'm pretty sure the new changes will allow that already.

[adamcameron]

Yup was about to suggest the same as this, @neokoenig.

Application code should not be in a web-accessible directory: only the entry point to the app should be. And the entry point should be a minimal stub Application.cfc (which does nothing more than extend the application's Application.cfc), and a minimal index.cfm that bootstraps the app.

And third-party code (so the wheels stuff) should be completely separate from the app code.

I did get this approach working with the current version of CFWheels at some point a while ago. I had to do a small amount of hacking of some wheels code from memory, but it wasn't too hard. Lemme see if I can find the blog article... https://blog.adamcameron.me/2021/05/short-version-getting-cfwheels-working.html

Oh... personally I would not have /app/tests, but have the two adjacent too each other (as /src and /tests) in the base app root dir. But this is a minor and opinionated point.

[bpamiri]

I actually like your scenario better than mine. I just checked we can identify the webroot in the server.json file so the user could start a server from the root of the application, but have it mapped to the web directory. That was my biggest hurdle in working with the new directory structure within CommandBox. Then, if we follow your "Other CFML" model, should the plugins folder be moved to the vendor folder?

[neokoenig]

Ultimately 3rd party plugins distributed - by say - forgebox, could be in vendor, but you might want a plugin dir for "your" local plugins.

All you'd need to is know which plugins / directories in vendor should be added to the plugin list so that wheels could scan/load them up as needed. That could be easily solved though.

Thinking of vendor - that should be on the gitignore list really, and then box install could just populate it.

This would work the same way composer in php does - you can nuke the vendor directory whenever you like and just do composer install to read from the composer.lock file.

[chapmandu]

I'm all in on Tom's suggestion, I'd also agree with the proposal for a "private/local" plugin directory for those that aren't published.

[bpamiri]

I agree the local plugins folder would be beneficial and could make plugin development easier as well. Keeping in mind that a couple of the other items being integrated for 3.0 are WireBox and TestBox, should there be a plugins folder in the vendor folder and keep plugins primarily the same or simply install plugins directly into the vendor folder and look at the plugins architecture as a whole. -Peter Amiri Sent from my iPhone (auto-typing mispell disclaimer in effect)On Jan 16, 2024, at 3:11 PM, Adam Chapman ***@***.***> wrote: I'm all in on Tom's suggestion, I'd also agree with the proposal for a "private/local" plugin directory for those that aren't published. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: ***@***.***>

[neokoenig]

"Should there be a plugins folder in the vendor folder and keep plugins primarily the same or simply install plugins directly into the vendor folder and look at the plugins architecture as a whole"

• I'd say wheels plugins should live alongside the same level as testbox, wheels etc in the vendor directory - they're just packages. Ultimately we (should) know which ones are wheels plugins, and we could make the installation process for a wheels plugin to simply be to add the package name to a json var or config file. could even read a custom object from box.json like wheels : { plugins: [ "foo" ] }

[bpamiri]

I like the plugins being first class citizens in the vendor folder and your right installation can be as simple as modifying a json file. Once the code gets integrated into the next day or so I'll test some of this and see how best to proceed.

[dbelanger]

Thing about plugins though is that Wheels needs to know they're plugins. At the moment, we rely on a directory named "plugins" and a zip file. If they become first class citizens of the Vendor directory, we'd need a file in each plugin directory which will declare them as Wheels specific plugins. I would also do away with the whole zip file concept.

[neokoenig]

Each wheels plugin on forgebox has

    "type":"cfwheels-plugins",

in box.json. At the moment we scan each plugin and read in the box.json to memory anyway, so I guess wouldn't be too far a stretch to look for that key and act appropriately.

Does bring up the issue that the current set of plugins will install into /plugins/ as that's what we told everyone to do (set the install path in box.json)

[timsayshey]

@dbelanger Yes! Please do away with the zip files! That's the first thing I turn off.

[bpamiri]

One final topic for discussion is what should be the name of the web folder. I've seen web, public, and webroot used in other projects. Rails uses public by the way. I like web by the way, but wondering if we should keep in line with rails.

[dbelanger]

I love public because it is more obvious to the user that anything in this directory will be made public. I find both web and webroot to be misused in a lot of apps as everyone seems to understand it differently.

[dhgassoc]

I like Tom's (neokoenig) directory structure, but with name of "public" (instead of "web").
Only other folder I would like to recommend adding is; /public/assets/docs/ {for application specific documentation}

Thanks Dan.G.

[mikegrogan]

I like the idea of the docs folder as well. I do something similar already.

[neokoenig]

I would perhaps query the requirement to add a docs folder to a publically accessible web directory? Unless I'm missing something

[adamcameron]

Same.

If I need a docs dir in my public dir for some reason... I'll add one.