Prisma 1 Forum

Feedback: Framework Preview

Introduction

In the Graphcool Framework, you can define the configuration of a Graphcool Service in the service definition graphcool.yml and deploy it to a Graphcool Service using the Graphcool CLI.

A service definition consists of type definitions, permissions, functions and root tokens (formerly called permanent authentication tokens).

After an initial closed beta period, we are now ready to open up the Graphcool Framework Preview :tada:
Everyone is invited to test out the Framework, no further steps are required to get started!

Getting Started

npm remove -g graphcool
npm install -g graphcool@next
graphcool init
graphcool # read usage information

Next Steps

Participation from the community in both repositories is highly appreciated. :slightly_smiling_face:

Migrating Legacy Projects

Going forward, evolving a given project will only be possible from either the Console or the CLI.

New projects created with the CLI are automatically part of the new workflow and can only be changed via the CLI.

Existing projects and new projects created with the Console are considered to be legacy projects that can only be changed using the Console. Additionally, these projects can be migrated to the new workflow manually. After you migrate a legacy project, it can no longer be changed in the Console.

You have to join the beta program to be able to migrate a legacy project, please send me a PM with your email address for more information.

image

After a project has been migrated, you can download its configuration from the project settings.

image

Notes

  • Legacy projects with an active integration, or with a PRE_WRITE function cannot be migrated to the Framework.

  • It’s not possible to reverse the migration of a legacy project.

  • Even after migrating a legacy project, you can still view and change its data using the Console. The Console’s databrowser and playground will continue to work for all projects.

  • The Framework will support workflows for multi-stage service deployments. More information about that soon!

Feedback

All commands included in the usage information of the CLI are expected to work. If you experience something else or have a feature request, please let us know in the Framework repository on GitHub: https://github.com/graphcool/graphcool

Thanks a lot for your help with shaping the future of backend development :muscle:
Best
– Nilan

5 Likes

This is exciting!

Two questions though:

Does this include the Email+Password integration?

If this is the case, can I turn off the integration, eject, then add back the Email+Password integration somehow?

Excited to try this out!

1 Like

Thanks for your questions, Devan! :slight_smile:

Integrations will not be supported by the CLI. With Schema Extensions we’re providing the right tools to build your own integrations - with the benefit of you as a developer having full control over the integration code, as it should be.

To improve the impaired developer experience, we’re maintaining a collection of Graphcool Modules. Specifically, to create a new project with email+password authentication, you can do this:

npm install -g graphcool@next
graphcool init
graphcool modules add graphcool/modules/authentication/email-password

I’d be happy to hear your feedback and suggestions on modules and the CLI! :pray:

Edit:

If this is the case, can I turn off the integration, eject, then add back the Email+Password integration somehow?

As I said above, the CLI does not support integrations. However, you can migrate from the existing email+password provider to the Graphcool Module and then eject your project :slight_smile: I can help with the migration if necessary.

1 Like

I have some questions:

  • How can I know what queries are available to use when creating a permission?

  • What is the node version is used to run the functions? Can I use async/await?

  • Can I use any npm module?

  • How can I share logic between functions?

1 Like

Those are great questions, thanks Victor!

How can I know what queries are available to use when creating a permission?

That’s a great point - we’ll need to add a Permission Playground that you can use to explore the available permission queries, as well as generate them. Here’s a proposal for that, and testing permissions as well: https://github.com/graphcool/graphcool-cli/issues/230

What is the node version is used to run the functions? Can I use async/await?

The function runtime is the same as before - you can’t use async/await, but adding 'use latest' in the first line adds ES6 support.

Can I use any npm module?

Yes, as discussed here: Changelog: Week 32 - 34

How can I share logic between functions?

Another great point! Right now, you can only share code by using node modules that you require separately - we’re thinking of improving this experience going forward :slight_smile:

Again, thanks a lot for your feedback!

Still cannot init from my existing project (timeout on the api) but I recreate a new one from scratch and it works like a charm :slight_smile:

It feels so good to be able to do everything on graphcool with a simple graphcool push and the modules so good

Works just perfectly :heart:

There is just few improvements that can be done:

  • add a watch command like that when we work on something there is automatic deployment
  • add some generators to create default file like graphcool generate function subscription xxx, graphcool generate permission User read

That really the only things that can be improved from what i’ve seen so far

Great job

2 Likes

Thank you Nilan! May you just briefly expand on the relationship (architectural/organisational) between modules and schema extensions? I’m unable to grasp where “modules” fit exactly within the project structure.

Modules are definitely not the same. With module you can just split your projects business logic and inside you can put kind of a “sub-project” that will be merged with your project. Let’s say you have a blog application to take a basic exemple, you want to implement a comment system, instead of adding this directly to your global types.graphql (that can become big over time) you can create a module comment with it’s own graphcool.yml that refer to a specific types.graphql file and only in this one you will have your Comment type and of course you can also add some functions specific to comments like a schema extension or any function you like and also you can manage your permission just related to the comments.

With modules you cannot do much more than what you do right now but it will be really good to organise your code and to not have with 1000 lines of code, you can split whatever you want. You can even if you want just have a special module that manage your permissions, one that manage your functions etc… this is your choice to know how to organise your codebase

I hope I answer your question and I hope I really understood the concept of modules, @nilan correct me if I’m totally wrong

2 Likes

thanks for your descriptions, @antho1404, I’ll add a few extra words :slight_smile:

Modules are very similar to projects, but they don’t have a .graphcoolrc file, and they can’t reference other modules in their graphcool.yml file. Those are the only two differences to a full Graphcool project.

You can add your own modules to a Graphcool project, simply by adding entries to the modules property in its graphcool.yml file. This will basically sum up all types, functions, permissions and root tokens of the modules and the base project when doing graphcool diff or graphcool deploy.

Modules collected in https://github.com/graphcool/modules are just premade modules that you can use, and after adding them with graphcool module add, there is no further connection between the local module and the remote module. So for example, there is no package or dependency system available for modules. These are topics we want to investigate further down the road :slight_smile:

Hope that clears up your questions, @Sammy!

1 Like

Yes, thank you both, @nilan and @antho1404!

1 Like

Does this mean that integrations in general have no long term future?

I guess they would be replaced by schema extensions - is that the direction of travel?

Great updates to the CLI!

I have one question/suggestion…

If I wanted to share a graphcool project on GitHub, as an open source project, I’d like to be able to tell people to run graphcool deploy and it should create a project ID automatically.

Is it a way to do this (perhaps with a flag?).

I understand .graphcoolrc holds this information but it wouldn’t be wise to share this, as the project ID wouldn’t be unique.

Love to hear your thoughts/suggestions.

Great work GC team!

1 Like

Great point @Jamie_Barton!

You can simply remove the .graphcoolrc or include it in .gitignore, then by running graphcool init in the root folder, the CLI will pick up the configuration graphcool.yml file and initialize a new project based on this. The new project id will be persisted into a new .graphcoolrc file :slight_smile: That’s exactly what we are doing for the examples repository: https://github.com/graphcool-examples/graphcool-examples

1 Like

Quick set of questions:

  • Any way to do a deploy dry run? or just a validation pass?
  • Is data copied when running graphcool init from an existing project? If not, is there any way to copy data via the CLI?
  • I cant access the data browser or the playground for my CLI-created projects. Is this intended?
  • I cant deploy due to an error that looks like this: “unhandled error: Wrong operation defined for ModelPermission. You supplied: ‘*’”. Any suggested workaround? The code thats failing is generated by the CLI.
  • Any way to create a new environment / project via the CLI, without spawning a bunch of files? Ideally it would be added to the .graphcoolrc file as well. Use case: A developer is working on a bugfix and would like his own copy environment to experiment in. Essentially a branch of the project.
  • Any way to manage billing levels of projects via the CLI?
  • Is there a github issue for the “logs” command? Would help a lot with local development
  • The function names I defined in the console are erroring in the cli. “The function name does not match the naming rule. Name: ‘Send push notifications’”. What are the naming rules?
  • Any way to subscribe to the logs? Would like to be able to set up alarms and whatnot.
  • Any way to set up a function that’s called on an interval? Like a cron job. Would be good, to get feature parity with serverless or similar services.
1 Like

Awesome. I feel like an idiot. I’ve followed these steps so many times with the examples.

Something else cropped up too…

I tried running graphcool init with the kitchen-sink Schema but receive:

▸ The type User is a system type and cannot be removed.

This also happened with a project of my own.

No User type is defined in the types file but I assumed Graphcool would build this automatically.

That’s a lot of questions, thanks so much for your feedback! I’ll answer them one by one.

  1. Doing graphcool diff will do a validation step and generate and list the pending operatioans. There’s also a feature request for a dedicated check command.

  2. This option is not available, no. The best way to transform data that’s currently available is by querying or exporting the data, and importing it again using a script. We’re looking to improve this workflow, here’s a pending PR for a JSON import.

  3. This happens when your project doesn’t have the User or File type - we’ll adjust the Console to account for these types now being optional soon.

  4. Could you please create a bug report here: https://github.com/graphcool/graphcool?

  5. Looks like there is no way to add a new project environment yet, could you create a feature request: https://github.com/graphcool/graphcool-cli?

  6. Any way to manage billing levels of projects via the CLI? That’s currently only possible in the Console - what have you thought of here for the CLI?

  7. graphcool functions gets you a list of function names, whereas graphcool logs -f <name> --tail let’s you hook into the logs of function <name>.

  8. We recently changed the naming requirements, function names now only can contain alphanumeric characters, - and _. This check is only applied when creating a new function or updating an existing one.

  9. This makes a lot of sense - a similar feature request is already there: https://github.com/graphcool/graphcool/issues/150 We’ll add more dashboard functionalities to the Console going forward to have better insights into query permformance, function logs and failed invocations.

  10. Another feature request: https://github.com/graphcool/graphcool/issues/142 So far, the easiest way for cron jobs is to use an external provider with a webhook feature.

Those were quite a few questions :smiley: Keep them coming, loving the amount of feedback this gets :green_heart:

Thanks for the answers.

Regarding billing:

Ideally, I would like another management / billing level. A level above the project which is more of an overall view of your projects, where I can manage payment methods, team etc.

Let’s say I have four different environments. It would be nice to have them count towards the same quota, and have a shared billing method for all of them.

Regarding the CLI: Most new environments are going to hit the free usage tiers quite fast, and even dev environments might have to upgrade their billing level. It would be nice to do this automatically / via the CLI instead of having to use the GUI. Mostly a nice-to-have :slight_smile:

That’s indeed the direction of travel - we will release more information about the transition from integrations to custom resolvers soon.

The reasoning behind this decision is that custom resolvers provide full control to developers, for a little bit of extra setup, which we alleviating by providing preconfigured Graphcool Modules.

I’d be very happy for the input of the community about the usability of the modules - also which modules you’d like to see in the future. Currently, I’m porting over some of the great Graphcool Functions provided by the community :slight_smile:

Question: How does the types.graphql file within a module relate to the types.graphql file of my project? Also, what is the relation between the root tokens a module vs project?